Skip to content

Content Management Workflow

This guide explains how to add and manage content in the Sky Tech Docs MkDocs site.

Quick Add Content Workflow

1. Add New Section

When adding a new content category (like R&D docs):

# Create directory in docs/
mkdir -p docs/new-section-name

# Add to mkdocs.yml navigation
# Edit mkdocs.yml and add under nav:
# - New Section: new-section-name/

2. Add Individual Files

# Place markdown files in the appropriate folder
cp your-files.md docs/section-name/

# Files are automatically discovered by MkDocs

3. Update Navigation (Optional)

For specific file organization, edit mkdocs.yml:

nav:
  - Home: index.md
  - Your Section:
    - Overview: section/index.md
    - Specific File: section/specific-file.md
  # Or for auto-discovery:
  - Your Section: section/

Content Organization

Current Structure

docs/
├── getting-started/     # Installation, quickstart
├── guides/             # User guides and workflows
├── research/           # R&D documentation
├── prompts/            # AI prompts and templates
└── about/              # Site information

Adding New Categories

  1. Create folder: docs/category-name/
  2. Add to navigation: Edit mkdocs.yml line ~195
  3. Test locally: poetry run mkdocs serve

Git Workflow

Publishing Changes

# 1. Check status
git status

# 2. Add changes
git add docs/ mkdocs.yml

# 3. Commit with descriptive message
git commit -m "Add [category] documentation
- Created docs/category/ directory
- Updated navigation in mkdocs.yml"

# 4. Push to GitHub
git push

Auto-Deploy

  • Changes to main branch trigger automatic deployment
  • Site available at: https://docs.craftman.dev/

File Naming Conventions

  • index.md - Section overview page
  • YYYY-MM-DD-topic.md - Dated content
  • kebab-case-names.md - General files
  • overview.md, getting-started.md - Standard pages

Frontmatter Template

---
title: "Page Title"
date: 2025-01-30
tags: [tag1, tag2]
status: draft/active/archived
---

Testing and Development

Local Development

# Start development server
poetry run mkdocs serve

# Custom port
poetry run mkdocs serve -a localhost:3000

# Build only (no server)
poetry run mkdocs build

Quality Checks

# Format code
poetry run black .

# Lint checks
poetry run ruff check .

# Fix lint issues
poetry run ruff check . --fix

MkDocs Features

Enhanced Markdown

  • Admonitions: !!! note "Title"
  • Code blocks: With syntax highlighting
  • Tabs: === "Tab 1"
  • Mermaid diagrams: In fenced code blocks
  • Tables, footnotes, task lists
  • Auto-discovery: - Section: folder/
  • Manual listing: Explicit file paths
  • Index pages: index.md becomes section landing

Troubleshooting

Common Issues

  • 404 errors: Check file paths in mkdocs.yml
  • Build failures: Verify markdown syntax
  • Missing navigation: Add section to nav: in config

Reset Workflow

# If navigation gets messy, use auto-discovery
# In mkdocs.yml, replace detailed nav with:
- Section Name: folder-name/

Quick Reference

Task Command
Add section mkdir docs/name && edit mkdocs.yml
Test locally poetry run mkdocs serve
Deploy git add . && git commit -m "msg" && git push
Auto-nav - Section: folder/ in mkdocs.yml
Manual nav List files explicitly under section