GitHub Sync

GitHub Sync keeps a DocStar collection up to date with Markdown files in a GitHub repository. Write docs in a docs/ folder, push to your branch, and a GitHub Action sends the changes to DocStar.

#

How it works

  1. You add a DocStar workflow file to your repository.
  2. On every push to your branch that changes files in docs/, the workflow finds the files that were added, changed or deleted.
  3. It sends them to DocStar using your API token.
  4. DocStar creates, updates or removes the matching pages in your collection.

The first run sends every file in docs/.

#

Set it up

#

Step 1: Add the workflow file

Run these commands in the root of your repository. Replace <collectionId> with your collection's ID (you can find it in the collection's URL in DocStar, after /collection/). Change branch=main if you publish from another branch.

# Create the workflows folder
mkdir -p .github/workflows

# Download the DocStar workflow for your collection
curl --fail "https://api.docstar.io/p/generate-docstar-workflow/<collectionId>?branch=main" \
  -o .github/workflows/docstar.yml

# Optional: download the DocStar Markdown format guide
curl "https://api.docstar.io/docstar.md" -o docstar.md
#

Step 2: Add your API token as a secret

  1. Create an API token in DocStar. See API Tokens.
  2. In your GitHub repository, go to Settings → Secrets and variables → Actions.
  3. Click New repository secret.
  4. Name it DOCSTAR_API_KEY and paste the token as the value.
  5. Save.
#

Step 3: Commit and push

git add .github/workflows/docstar.yml
git commit -m "Add DocStar sync workflow"
git push origin main

From now on, every push that changes files in docs/ syncs to your collection. You can follow each run in the repository's Actions tab.

#

Organise your files

The folder structure inside docs/ becomes the page structure in DocStar.

  • Folders become parent pages or sections.
  • Files become pages or API endpoints.
  • A page.md file inside a folder holds the content for that folder's own page. Without it, the folder is just a container for its children.
docs/
├── getting-started.md        page
├── api/                      section
│   ├── page.md               content of the "api" page
│   ├── authentication.md     page under "api"
│   └── users/                nested section
│       └── create.md         page under "api/users"

Use only lowercase letters, numbers, - and _ in file and folder names so page URLs stay clean.

#

Write each file

Every file needs the .md extension and a YAML front matter block at the top.

Field Type Description
type string page (default) or endpoint
title string Page title
description string Short summary
published boolean true publishes the page right away 
---
type: page
title: Getting Started
description: Welcome to our documentation.
published: true
---
# Welcome
This is the content of the page.
#

API endpoints

For type: endpoint, write an OpenAPI (Swagger) snippet below the front matter:

---
type: endpoint
title: Create User
published: true
---
post: /users
summary: Create a new user
parameters:
  - name: username
    in: body
    required: true
    schema:
      type: string
responses:
  200:
    description: User created successfully
#

Tips

  • Deleting a file in docs/ deletes the matching page in DocStar on the next sync.
  • Edits made in DocStar can be overwritten the next time the file changes in GitHub. Treat the repository as the source of truth.
  • For a one-time import instead of ongoing sync, see Import Content.
Built with DocStar