How to make content changes to API guidance

This document is designed to assist content editors with making changes to the API guidance pages. The general steps to make changes to API guidance are:

Start a Github Codespace

GitHub Codespaces enable you to make changes to the application/guidance pages in a pre-configured environment from within your browser. To use Codespaces you will need:

• A GitHub account (via a tools request in #digital-tools-support on Slack)
• To be part of the DFE-Digital GitHub organization (go to your organisations list and look for DFE-Digital).
• Be granted access to the RECT public repository.
• Have Codespaces enabled for your account.

Start by creating a branch to work from. You can do this by navigating to the branches section in the GitHub repository and clicking New branch. Here, enter a branch name to describe your changes and click Create new branch:

Now we can switch to our branch by navigating to the main repository page and selecting the branches drop-down, searching for and choosing our branch:

Finally, we want to start a Codespace on this branch by clicking Code -> Create codespace on <your branch name> (you should see “Codespace usage for this repository is paid for by DFE-Digital.” in the dialog):

The first time you create a Codespace it can take quite a while to spin up.

Once Codespace is ready click on the TERMINAL tab and enter command ./bin/dev to start rails application. This allows you to preview things live before committing them. You know its ready when the PORTS tab contains a port of 3000:

Navigate to/create the Markdown file for the guidance page

In order to create/edit a guidance page you have to navigate to the folder that contains the Markdown files that make up each page. Navigate to the app/views/api/guidance in the file explorer:

Here, you can either find the existing file you want to edit or create a new .md file to add a guidance page. The folder structure will mimic the final URL given to the page, for example:

• app/views/api/guidance/page-1.md will be available at /api/guidance/page-1
• app/views/api/guidance/nested/page-2.md will be available at /api/guidance/nested/page-2

Construct the page/contents using supported Markdown syntax

Write the content of the guidance page using Markdown, which we will later transform into HTML. An example page would be:

# Main heading

## Sub-heading 1

Some content here

## Sub heading 2

Some more content here with [a link](http://link.com) and a code block:

```json
{
  "name": "test",
  "title": "Test",
  "description": "This is a test page",
  "type": "markdown"
}
```

The sub-headings (any second-level heading) will appear as a link in the sidebar. If you’re not familiar with Markdown you can reference this cheat sheet.

Adding a Page to the ‘Guidance’ Section

To add a new page to the Guidance section:

1. The URL must begin with: /api/guidance/guidance-for-lead-providers/
2. The page must be be added to the list in API::Guidance::SidebarComponent.

1. Create the Guidance Page

1. Write the page content in Markdown.
2. Save the file in folder: app/views/api/guidance/guidance_for_lead_providers/

Example: app/views/api/guidance/guidance_for_lead_providers/api_data_states.md

2. Add the Page to SidebarComponent

1. Edit the component file: app/components/api/guidance/sidebar_component.rb
2. Update the GUIDANCE_PAGES constant to include the new page:

GUIDANCE_PAGES = [
  { title: "API IDs explained", path: "api-ids-explained" },
  { title: "API data states", path: "api-data-states" },
  { title: "Syncing data best practice", path: "data-syncing" },
  { title: "New API guidance page", path: "new-api-guidance-page" }, # <-- New entry
].freeze

Field definitions:

• title — The page title shown in the left menu.
• path — The part of the URL after /api/guidance/guidance-for-lead-providers/.

Example: For the URL: /api/guidance/guidance-for-lead-providers/new-api-guidance-page the path is: new-api-guidance-page

Preview your changes

When you want to view your changes as they will appear on the website, navigate to the PORTS tab in GitHub Codespaces and right click -> Open in browser. You can then input the path to the guidance page you are editing in the URL of the browser (see Navigate to/create the Markdown file for the guidance page if you’re unsure of what the path will be).

Raise a pull request

When you’re happy with your changes, you need to commit them and raise a pull request in GitHub that can be merged down/deployed.

You can do this by navigating to the Source Control section of Codespaces and clicking the Commit button. If you get a dialog about staging changes, you can select Yes or Always:

Once committed, you can open the pull requests tab in GitHub and you should be prompted to create a new pull request:

Seek approval/merge your changes

With your pull request raised, all that’s left is to get a developer on the team to review your changes. Once reviewed, you will be able to merge the changes and this will deploy them to production.