SkyCMS Docs Publisher

This repo is a ready-to-run template for publishing Markdown docs to SkyCMS.

What this provides

• A docs folder structure under Docs/
• The SkyCMS docs importer script under .skycms/scripts/
• A GitHub Actions workflow to sync content
• A hash map file for idempotent imports

Requirements

• A SkyCMS site with the Docs Import API enabled
• API key and service account user ID configured in SkyCMS
• GitHub repository secrets:
  • SKYCMS_API_URL
  • SKYCMS_API_KEY
  • SKYCMS_TENANT_HOST

Repository layout

Docs/
  Getting-Started/
    index.md
    img/
      logo.txt
.skycms/
  docs-import-map.json
  scripts/
    import-docs.js
.github/
  workflows/
    docs-import.yml

How it works

• CI detects changes under Docs/** or .skycms/**
• The importer converts Markdown to HTML and calls the SkyCMS import API
• Assets are uploaded to /pub/docs
• Hashes are tracked in .skycms/docs-import-map.json

Quick start

1. Add your Markdown content under Docs/
2. Configure GitHub secrets
3. Push changes and let the workflow run

For details, see QUICK_START.md.

Front matter cheat sheet

Key	Purpose	Example
title	Page title	Getting Started
summary	Intro text	Short intro
published	Publish flag	true
published_at	Publish timestamp	2026-02-08T00:00:00Z
url_path	Custom URL path	docs/getting-started
banner_image	Banner image URL	/pub/docs/getting-started/hero.png
article_type	Article type	General

Repo checklist

• Set SKYCMS_API_URL, SKYCMS_API_KEY, SKYCMS_TENANT_HOST secrets
• Keep content under Docs/ with index.md for section roots
• Store assets next to pages and use relative paths
• Commit .skycms/docs-import-map.json so hashes persist
• Run Jest tests in JestTests/ if you modify the importer

Troubleshooting

• 401 Unauthorized: check SKYCMS_API_KEY and SkyCMS DocsImport:ApiKey
• 403 Forbidden: verify the service account permissions
• 413 Payload Too Large: reduce page size under 1 MB or split content
• 429 Too Many Requests: slow down commits or increase rate limits
• Missing assets: confirm relative paths and asset file location

Docs style guide

• Use a single H1 per page
• Keep section headings in order (H2 -> H3)
• Prefer relative links for internal pages
• Keep images under 25 MB and use descriptive names