{"id":"697ab4e14bcd26c09b04d611","title":"2026 01 29 Publishing Technical Articles","path":"how-to/technical-articles/2026-01-29-publishing-technical-articles","contentMarkdown":"# 29-Jan-2026 — Publishing Technical Articles\n\n_____\n\nThis article explains how to create and publish technical articles to the NGX-Ramblers CMS.\n\n## Overview\n\nTechnical articles are written in markdown and stored in `non-vcs/technical-articles/`. A publishing script handles uploading to the CMS and updating the index page automatically.\n\n## File Naming Convention\n\nFiles must start with a date in `YYYY-MM-DD` format. The full filename (minus extension) becomes the URL slug:\n\n| Example Filename | Published Path |\n|------------------|----------------|\n| `2026-01-29-input-source.md` | `how-to/technical-articles/2026-01-29-input-source` |\n| `2026-01-29-publishing.md` | `how-to/technical-articles/2026-01-29-publishing` |\n\n## Heading Format\n\nThe first heading determines the title shown in the index. Use this format:\n\n```markdown\n# DD-Mon-YYYY — Article Title [#123](https://github.com/nbarrett/ngx-ramblers/issues/123)\n```\n\nThe script extracts the title by removing the date prefix, so the index entry becomes:\n\n```\n- [29-Jan-2026 — Article Title](https://ngx-ramblers.org.uk/how-to/technical-articles/2026-01-29-article-name)\n```\n\n## Creating a New Article\n\n1. Copy the template:\n\n```bash\ncp non-vcs/technical-articles/TEMPLATE.md \\\n non-vcs/technical-articles/YYYY-MM-DD-article-name.md\n```\n\n2. Edit the content using standard markdown:\n - Use `## Heading` for sections\n - Use `### Subheading` for subsections\n - Use markdown tables (no HTML)\n - Use fenced code blocks with language hints\n\n## Publishing\n\nFrom the `server` directory:\n\n```bash\nCMS_USERNAME= CMS_PASSWORD= npx tsx lib/release-notes/publish-technical-article.ts \\\n ../non-vcs/technical-articles/YYYY-MM-DD-article-name.md\n```\n\nThe script will:\n1. Extract the date from the filename for the index entry\n2. Use the full filename slug for the URL path\n3. Extract the title from the first heading\n4. Publish to `how-to/technical-articles/`\n5. Add an entry to the index page (if not already present)\n\n## Environment Variables\n\n| Variable | Required | Default |\n|----------|----------|---------|\n| `CMS_USERNAME` | Yes | — |\n| `CMS_PASSWORD` | Yes | — |\n| `CMS_URL` | No | `https://www.ngx-ramblers.org.uk` |\n\n## Republishing\n\nRunning the publish command again will update an existing article. The index entry is only added once (duplicates are detected by path).\n\n## Related Files\n\n| File | Purpose |\n|------|---------|\n| `non-vcs/technical-articles/TEMPLATE.md` | Starting template for new articles |\n| `non-vcs/technical-articles/README.md` | Quick reference documentation |\n| `server/lib/release-notes/publish-technical-article.ts` | Publishing script |\n| `server/lib/release-notes/cms-client.ts` | CMS API client |\n","contentHtml":"

29-Jan-2026 — Publishing Technical Articles

\n
\n

This article explains how to create and publish technical articles to the NGX-Ramblers CMS.

\n

Overview

\n

Technical articles are written in markdown and stored in non-vcs/technical-articles/. A publishing script handles uploading to the CMS and updating the index page automatically.

\n

File Naming Convention

\n

Files must start with a date in YYYY-MM-DD format. The full filename (minus extension) becomes the URL slug:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Example FilenamePublished Path
2026-01-29-input-source.mdhow-to/technical-articles/2026-01-29-input-source
2026-01-29-publishing.mdhow-to/technical-articles/2026-01-29-publishing
\n

Heading Format

\n

The first heading determines the title shown in the index. Use this format:

\n
# DD-Mon-YYYY — Article Title [#123](https://github.com/nbarrett/ngx-ramblers/issues/123)\n
\n

The script extracts the title by removing the date prefix, so the index entry becomes:

\n
- [29-Jan-2026 — Article Title](https://ngx-ramblers.org.uk/how-to/technical-articles/2026-01-29-article-name)\n
\n

Creating a New Article

\n
    \n
  1. Copy the template:
    2. \n
\n
cp non-vcs/technical-articles/TEMPLATE.md \\\n   non-vcs/technical-articles/YYYY-MM-DD-article-name.md\n
\n
    \n
  1. Edit the content using standard markdown:
      \n
    • Use ## Heading for sections
      • \n
    • Use ### Subheading for subsections
      • \n
    • Use markdown tables (no HTML)
      • \n
    • Use fenced code blocks with language hints
      • \n
    \n
    2. \n
\n

Publishing

\n

From the server directory:

\n
CMS_USERNAME=<user> CMS_PASSWORD=<pass> npx tsx lib/release-notes/publish-technical-article.ts \\\n  ../non-vcs/technical-articles/YYYY-MM-DD-article-name.md\n
\n

The script will:

\n
    \n
  1. Extract the date from the filename for the index entry
    2. \n
  2. Use the full filename slug for the URL path
    3. \n
  3. Extract the title from the first heading
    4. \n
  4. Publish to how-to/technical-articles/<filename-slug>
    5. \n
  5. Add an entry to the index page (if not already present)
    6. \n
\n

Environment Variables

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
VariableRequiredDefault
CMS_USERNAMEYes—
CMS_PASSWORDYes—
CMS_URLNohttps://www.ngx-ramblers.org.uk
\n

Republishing

\n

Running the publish command again will update an existing article. The index entry is only added once (duplicates are detected by path).

\n

Related Files

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FilePurpose
non-vcs/technical-articles/TEMPLATE.mdStarting template for new articles
non-vcs/technical-articles/README.mdQuick reference documentation
server/lib/release-notes/publish-technical-article.tsPublishing script
server/lib/release-notes/cms-client.tsCMS API client
\n"}