Contribute to the docs

How to add a new page to the documentations site using Quarto?

Welcome to our guide on adding a new page to this documentation site using Quarto. Quarto uses Markdown allowing you to create and maintain high-quality, reproducible documents with ease.

In the following sections, we will cover the steps to create and deploy a new page into our NHS Quarto documentation site.

Clone the repository

Open your command prompt or terminal, and navigate to the directory where you want to clone the repository.

To clone the repository, use the following command:

git clone https://github.com/nhsengland/nhs-r-reporting.git

The URL can be found on the repository’s main page on GitHub.

The cloning process will create a new folder named after the repository in your chosen directory. Once the cloning is complete, navigate to the newly created folder:

cd nhs-r-reporting

Now you have a local copy of the repository on your computer. You can now start working on the project files and make changes.

Make a new branch of the repository

Creating a new branch in the repository allows you to safely work on new features or modifications without affecting the main project.

Before creating a new branch, ensure that you have the latest version of the main branch by executing the following commands:

git checkout main
git pull

To create a new branch and switch to it immediately, run the command:

git checkout -b <branch-name>

Replace <branch_name> with the desired name for your new branch.

Make a new .qmd (q-markdown) file in the /docs folder

Open the .qmd file add a YAML header with a title and subtitle.

---
title: Contribute to the docs
subtitle: "How to add a new page to the documentations site using Quarto?"
---

Below this line you can write your guide or contribution in markdown.

Think about accessibility

If you are writing a guide, please add alt text or captions to any images for accessibility. It helps people with visual impairments understand the content of the images. Here’s how you can add alt text and captions to images in a Quarto document:

1. Adding Alt Text

Alt text is a short description of an image that assists people with visual impairments. It is displayed if the image cannot be loaded or when a screen reader is used. To add alt text to an image in Quarto, use the alt attribute in the image syntax:

![](path/to/image.png){alt="A brief description of the image"}

Replace path/to/image.png with the path to your image file and provide a brief description of the image within the quotes following alt=.

2. Adding Captions

Captions are textual descriptions displayed below the image, providing additional context. To add a caption to an image in Quarto, use the fig.cap attribute in the image syntax:

![](path/to/image.png){fig.cap="Caption text for the image"}

Replace path/to/image.png with the path to your image file and provide the caption text within the quotes following fig.cap=.

3. Combining Alt Text and Captions

You can add both alt text and captions to an image in Quarto by including both the alt and fig.cap attributes in the image syntax:

![](path/to/image.png){alt="A brief description of the image" fig.cap="Caption text for the image"}

Replace path/to/image.png with the path to your image file, provide a brief description of the image within the quotes following alt=, and provide the caption text within the quotes following fig.cap=.

By including alt text and captions in your Quarto documents, you’ll make your content more accessible to a wider range of users.

Add a link to your file to the _quarto.yml config file in /docs

Open the _quarto.yml configuration file and find the sidebar config code.

sidebar:
  - id: nav
    style: "floating"
    collapse-level: 3
    align: left
    contents:

Under the contents: object add a new section (if required), a string lable for your page, and a link to the .qmd file itself.

- section: "RAP"
  contents:
    - text: "Reproducible Analytical Pipelines"
      file: intro-to-rap.qmd

Publish your changes to GitHub

Render Quarto before publishing

Remember to render your changes locally using R-Studio before publishing

Add all changes and commit locally

git commit -a -m 'Added new page to docs'

Then push your changes to the remote branch

git push origin <branch-name>

Finally, open a Pull Request (PR) https://github.com/nhsengland/nhs-r-reporting/pulls