The DocStar GitHub workflow allows you to automatically sync markdown documentation files from a GitHub repository's docs/ directory to your DocStar collection. Whenever a push is made to the configured branch (e.g., main), the GitHub Action detects changes (Added, Modified, Deleted) in the docs/ folder and sends them to the DocStar Collection.

To integrate the DocStar sync workflow into your GitHub repository, follow these steps:

Run the following curl command in the root of your project repository. Replace <your-api-domain> with your actual API domain and <collectionId> with your DocStar Collection ID.

# Create the workflows directory if it doesn't exist

mkdir -p .github/workflows




# Download the workflow yaml file directly into the workflows directory

curl "https://api.docstar.io/p/generate-docstar-workflow/<collectionId>?branch=main" -o .github/workflows/docstar.yml





# Download the DocStar Markdown specification file.

curl "https://api.docstar.io/docstar.md" -o docstar.md

The workflow requires an API key to securely communicate with the DocStar backend.

1. Go to your GitHub repository on github.com.

2. Navigate to Settings > Secrets and variables > Actions.

3. Click on New repository secret.

4. Name the secret DOCSTAR_API_KEY.

5. Paste your DocStar API token as the value and save.

Commit the new workflow file and push it to your repository:

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

Once pushed, any subsequent changes to markdown files inside the docs/ directory will automatically trigger the GitHub Action and sync to your DocStar Collection.

This document provides technical specifications for synchronizing documentation from a GitHub repository to Docstar.

All documentation must reside within a root directory (typically named docs/). The folder structure within docs/ defines the hierarchy and navigation of the published site.

• Folders: Represent categories or parents.

• Files: Represent individual pages or endpoints.

If a folder contains a page.md file, the content of this file becomes the content for that specific folder (the "parent" page). Without page.md, the folder acts as a container for its children.

Example Structure:

docs/
├── getting-started.md      (Individual page)
├── api/                    (Folder/Category)
│   ├── page.md             (Content for the 'api' category page)
│   ├── authentication.md   (Page under 'api')
│   └── users/              (Nested Folder)
│       └── create.md       (Page under 'api/users')

Files must use the .md extension and include a YAML frontmatter section.

Required and optional fields:

Example Page:

---
type: page
title: Getting Started
description: Welcome to our documentation.
published: true
---
# Welcome
This is the markdown content of the page.

For files with type: endpoint, the content below the frontmatter is expected to be an OpenAPI / Swagger snippet.

Example Endpoint:

---
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

Docstar synchronizes via a GitHub Action that sends a JSON payload to the /import/github endpoint.

• Do use page.md for folder-level content.

• Do include YAML frontmatter in every file.

• Do use type: endpoint for API documentation.

• Do maintain a clean folder hierarchy.

• Don't use characters other than a-z, 0-9, -, and _ in file/folder names (to ensure clean URLs).