Skip to content

Publishing workflow

Publishing Workflow (Internal)

This document describes the process for adding blog posts and guides to the Halite Systems site.

This page is intentionally not indexed in navigation.

Blog Post Workflow

1. Create the file

Location:

docs/blog/posts/

Filename format:

YYYY-MM-DD-short-title.md

Example:

2026-03-02-salt-master-failover-notes.md

2. Add frontmatter

At the top of the file:

date: 2026-03-02 categories:

  • Architecture tags:
  • salt
  • ha
  • gitfs

Notes:

  • date controls ordering
  • categories appear under the post title
  • tags populate the Tags page

3. Write the content

Minimum structure:

  • Title
  • Opening paragraph
  • Main content

Keep posts implementation-focused. Avoid marketing language.

Use relative links to avoid MkDocs warnings.

Good:

GitFS Guide

Avoid:

/guides/salt/gitfs-ssh-auth/

5. Preview locally

From repository root:

mkdocs serve

Check:

  • Post appears at top of Blog
  • Tags render correctly
  • No warnings in terminal
  • Links function

6. Commit and publish

git add . git commit -m "Add blog post: short description" git push

GitHub Actions handles deployment automatically.

Verify:

Guide Publishing Workflow

For full guides:

  1. Place file under appropriate directory, e.g. docs/guides/salt/
  2. Add entry to mkdocs.yml under: Knowledge Base → Guides → Salt
  3. Run mkdocs serve
  4. Commit and push

Naming Conventions

Blog:

  • YYYY-MM-DD-topic.md

Guides:

  • descriptive-topic-name.md

Avoid spaces in filenames.

Pre-publish Checklist

  • Correct frontmatter
  • Relative links only
  • No MkDocs warnings
  • Appears correctly in Blog or Guides
  • Tags appropriate and minimal
  • Commit message clear and descriptive