# 29-Jan-2026 — Publishing Technical Articles

_____

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

## Overview

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.

## File Naming Convention

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

| Example Filename | Published Path |
|------------------|----------------|
| `2026-01-29-input-source.md` | `how-to/technical-articles/2026-01-29-input-source` |
| `2026-01-29-publishing.md` | `how-to/technical-articles/2026-01-29-publishing` |

## Heading Format

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

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

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

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

## Creating a New Article

1. Copy the template:

```bash
cp non-vcs/technical-articles/TEMPLATE.md \
   non-vcs/technical-articles/YYYY-MM-DD-article-name.md
```

2. Edit the content using standard markdown:
   - Use `## Heading` for sections
   - Use `### Subheading` for subsections
   - Use markdown tables (no HTML)
   - Use fenced code blocks with language hints

## Publishing

From the `server` directory:

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

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

## Environment Variables

| Variable | Required | Default |
|----------|----------|---------|
| `CMS_USERNAME` | Yes | — |
| `CMS_PASSWORD` | Yes | — |
| `CMS_URL` | No | `https://www.ngx-ramblers.org.uk` |

## Republishing

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

## Related Files

| File | Purpose |
|------|---------|
| `non-vcs/technical-articles/TEMPLATE.md` | Starting template for new articles |
| `non-vcs/technical-articles/README.md` | Quick reference documentation |
| `server/lib/release-notes/publish-technical-article.ts` | Publishing script |
| `server/lib/release-notes/cms-client.ts` | CMS API client |