SSW.Rules

This is a Next.js + TinaCMS website pulling data from:

• SSW Rules Content Repo 📜

Architecture Diagram

Getting Started

Required Tools

• Node.js (version defined in .nvmrc) – recommended to use nvm
• corepack (run corepack enable to manage correct pnpm version)
• pnpm package manager
• python

F5 experience

1. Clone this repo

2. Clone SSW.Rules.Content

3. Place both repos in the same parent directory e.g.

📁 SSW-dev/
├── 📁 SSW.Rules.Content/
└── 📁 SSW.Rules/ <--- This repo

1. Create a .env file based off .env.example in the root of this repo - get the values from Keeper (SSW.Rules Environment Variables)

2. Run pnpm install to install packages

3. Install pyyaml python package: py -3 -m pip install pyyaml

4. Run pnpm prepare:content to generate required mapping JSON files (they are gitignored)

5. Run pnpm dev to start the development server

Syncing and Updating Content

To test changes to MDX rules:

1. Go to your branch in SSW.Rules.Content

2. Modify the rule MDX as needed

3. If there are any changes to categories, re-run pnpm prepare:content

4. Run pnpm dev in this project to start SSW.Rules locally

5. Navigate to http://localhost:3000/rules/ to see your changes

Note: pnpm dev does not track changes in SSW.Rules.Content, therefore, you will need to re-run the command after you make changes

Branches

• Always create a new branch for your PBIs
• Always delete your branch once your PR has been merged
• To create a new content branch (in SSW.Rules.Content), follow the setup steps in the Wiki

Builds & Deployment

Content Changes (SSW.Rules.Content)

Changes made in SSW.Rules.Content (e.g. rule MDX, categories, images) will go live after the PR is merged.

🎥 Watch the video: TinaCMS for GitHub - The SSW Rules Migration | Jake Bayliss | SSW Consulting

---

Code Changes (SSW.Rules)

Code changes made to SSW.Rules are deployed as follows:

• main deploys to staging: https://app-sswrules-staging.azurewebsites.net/rules
• To deploy to production:
  • Create a release/xx branch from the current main commit you want to ship
  • Manually run the production deployment workflow in GitHub Actions
  • production: https://www.ssw.com.au/rules

PR Preview Deploy

To deploy a PR preview, add a comment to the PR: /deploy. This creates/updates a preview deployment (slot pr-<number>) and posts a comment with the preview URL.

Using a custom tina-lock.json in a PR preview

The build process checks whether a branch with the same name as the PR branch exists in SSW.Rules.Content. If found, that branch is used to source content (including tina-lock.json); otherwise it falls back to main.

This means if your PR requires a new tina-lock.json (e.g. you added or changed a TinaCMS collection), you can test it in the PR preview without touching main in the content repo:

1. Create a branch in SSWConsulting/SSW.Rules.Content with the exact same name as your PR branch.
2. Push the updated tina-lock.json (and any other content changes) to that branch.
3. Comment /deploy on the PR - the preview build will automatically pick up the matching content branch.

---

Python Scripts

In this Repository (Website)

• build-rule-category-map.py
  Generates two JSON files:

  • rule-to-categories.json (maps rules to categories)
  • category-uri-title-map.json (maps category URIs to titles)
  • orphaned_rules.json (maps category URIs to titles)
    Reads rule data from the SSW.Rules.Content repo and runs during the build process (via GitHub Actions) or manually from scripts/tina-migration.

• prepare-content.js
  A Node.js script that runs build-rule-category-map.py and moves the JSON files to the correct location for use by the website.
  Uses the LOCAL_CONTENT_RELATIVE_PATH environment variable to locate the content repo.

• validate-rule-categories.js
  Fails when a non-archived rule has no category, or when a rule's categories frontmatter points at a category file that doesn't exist (e.g. after a category was moved), naming every offending rule.
  Runs in prepare-content.js and in the build workflow before the Docker build, so the build fails in seconds instead of as a /archived prerender error.
  When the check passes, it also writes rule-folders.json, the rule list that generateStaticParams reads.
  Run it manually with pnpm validate:rule-categories, which uses LOCAL_CONTENT_RELATIVE_PATH, or pass the content repo path as an argument.

In the Content Repository

• build-rule-category-map.py
  Similar logic to the version in PoC. It processes the categories/ folder and .mdx files to create the same JSON maps.

• convert-rule-md-to-mdx.py
  Converts .md rule files to MDX format compatible with TinaCMS.
  Replaces custom markdown patterns (e.g., Figure, good/bad/ok boxes) with structured MDX components like <asideEmbed> and escapes special characters for valid formatting.

• modify-sub-categories-frontmatter.py
  Updates frontmatter in sub-category files (excluding index.md) to ensure consistency.

• modify-top-categories-frontmatter.py
  Targets index.md files in sub-category folders and updates frontmatter to match the expected format.

• modify-main-category-frontmatter
  Updates index.md file at the root of the categories folder.

---

📁 Public Content Folder

All rule content (including .mdx files and images) live into the public/ folder.

🎥 The 3 options for storing markdown in GitHub for TinaCMS

public/
└── uploads/
    └── rules/
        ├── rule-a/
        │   ├── rule.mdx
        │   └── img.png
        └── rule-b/
            ├── rule.mdx
            └── img.png

---

📝 Adding Editorial Workflow

We've integrated TinaCMS with an editorial workflow to support content editing in a more structured way. If you're unfamiliar with how editorial workflows work in Tina, please refer to the official documentation:

👉 TinaCMS Editorial Workflow Documentation

This workflow allows for content changes to be reviewed before being published, improving collaboration and content quality.

🔖 Bookmarks (via SSW.Rules.Functions)

The Bookmark feature uses the SSW.Rules.Functions API.

Local debugging setup

1. Clone the SSW.Rules.Functions repository.
2. In the repo root, create a local.settings.json file and copy the values from Keeper (environment variables for the Functions app).
3. Start the Functions app in dev mode.

Local endpoint

• By default, the API is available at: http://localhost:7248.

• Bookmark data is persisted to the staging database.

• Install nodejs version specified in .nvmrc (Ideally use nvm to use the right version)

• Ensure corepack is enabled - corepack enable (this allows auto-install of the correct yarn version)

Getting ready for development

• Clone the repo from https://github.com/SSWConsulting/SSW.Rules

• Run yarn install to install packages

• Create environment files .env.development based off .env.template - get the values from Keeper (SSW.Rules Environment Variables)

• For GitHub App authentication, set the following environment variables:

  • GH_APP_ID: Your GitHub App ID
  • GH_APP_PRIVATE_KEY: Your GitHub App private key (PEM format, can be base64 encoded)
  • GITHUB_APP_INSTALLATION_ID: (Optional) The installation ID. If not provided, the first installation will be used.

  See GitHub App authentication documentation for more details.