GIG Cymru NHS Wales - Product Briefs

The documents in this repository are published to https://gigcymru.github.io/product-briefs/.

Getting Started

There are several ways to set up your development environment:

1. GitHub Codespaces (Recommended)

The fastest way to start contributing:

This provides:

• A pre-configured VS Code environment (with useful extensions installed)
• All required dependencies installed
• Automatic port forwarding for preview
• Git integration

Once you have successfully launched Codespaces you can run the development server from the VS Code Terminal:

    make run

You will be prompted to Open in Browser to view the locally running site.

See the Quickstart Guide for more information.

Note: It can take a few minutes to fully launch Codespaces the first time, but is faster on subsequent launches as the environment is then cached.

2. Local Development

Prerequisites:

• Python 3.11 or higher
• uv for package/env management
• Git

Setup Steps:

Clone the repository:

    git clone git@github.com:GIGCymru/product-briefs.git
    cd product-briefs

Install uv (if not already installed):

    curl -LsSf https://astral.sh/uv/install.sh | sh

Set up environment and dependencies:

    uv sync

Start the development server:

    uv run mkdocs serve

View the documentation at: http://127.0.0.1:8000/

3. Container-based Development

If you prefer using containers:

Prerequisites:

• Podman or Docker

Setup Steps:

Build the container:

    podman build --tag mkdocs .

Run the development server:

    podman run -p 8000:8000 mkdocs

View the documentation at: http://127.0.0.1:8000/

4. Make-based Workflow

For those familiar with Make:

    # See available commands
    make help

    # Full build and serve
    make

View the documentation at: http://127.0.0.1:8000/

Converting Markdown to Word

This repository includes a GitHub workflow to automatically convert specific Markdown files into Microsoft Word documents. This is useful for sharing formatted documents with stakeholders who may prefer Word format.

The conversion is handled by Pandoc, a universal document converter.

Automated Workflow

The GitHub Action workflow is defined in .github/workflows/markdown-to-word.yml. It is triggered on pushes to the main branch for files to be converted.

When triggered, the workflow creates a new release with the converted .docx files.

Manual Conversion

You can also run the conversion manually. This is helpful for testing changes to the templates or the style reference file before pushing to the repository.

Prerequisites:

• Pandoc installed on your local machine.

Command:

To convert the documents, run the following command from the root of the repository:

# Convert all markdown files to word documents
make word

Styling

The appearance of the generated Word documents is controlled by a reference document: .github/workflows/markdown-to-word-styles.docx. To change the styling (e.g., fonts, headings, spacing), you can edit the styles within this .docx file in Microsoft Word, save your changes, and commit the updated file. Pandoc will then use the styles from this reference document during conversion.

Documentation

Our documentation is built using Material for MkDocs.

Contributing

1. Choose your preferred development environment from above
2. Create a new branch for your changes
3. Make your changes
4. Test your changes locally
5. Submit a Pull Request

License

This repository is licensed under the MIT License