GitHub Sync

Scalar GitHub Sync allows you to author your documentation as markdown in your own repository and automatically publish it as a beautiful website.

Getting startedCopied!

The following guide takes you from zero to deployed documentation in just a few minutes.

Set up your docs repositoryCopied!

Use your existing GitHub repository, or create a new one from our template repository. If you're using the template repository, you can skip to "Configuration".

Add some content

If you have a few Markdown files already, that’s awesome. Otherwise, just create a new docs folder and add at least one Markdown file:

# Create a docs/ folder
mkdir docs

# Create an example file
echo "# Hello World" > docs/introduction.md

That should be enough to prepare your content. Time to configure your project, let’s create a Scalar configuration file:

touch scalar.config.json

Configuration

Add the content below to your scalar.config.json file. Note: You want to modify the subdomain. The one in the example is already taken. 😉 Your docs site will be automatically available at https://<subdomain>.apidocumentation.com, but you can also use a custom domain, see Advanced configuration for more information.

{
  "$schema": "https://cdn.scalar.com/schema/scalar-config.json",
  "subdomain": "my-awesome-documentation",
  "guides": [
    {
      "name": "My awesome documentation",
      "sidebar": [
        {
          "path": "docs/introduction.md",
          "type": "page"
        }
      ]
    }
  ],
  "references": []
}

Make sure to commit and push the changes to your repository.

Connect your repository to ScalarCopied!

Create a free Scalar account here: https://dashboard.scalar.com/register

Once signed in, click on “Link GitHub Account”. You’ll be redirected to GitHub, where you can connect your account, then you’ll be redirected back to Scalar.

Find your repository and click on “Link Repository”.

Publish changesCopied!

To publish your site for the first time, click on “Publish". Now sit back and relax, your documentation is being generated for you and deployed to our super fast edge servers, this will take a few minutes.

Once done, you’ll see "Deployment Live" in the right hand column and a link to your new documentation site. Congratulations, you’ve made it!

Advanced configurationCopied!

There’s definitely more to configure. Here are some more options for you:

Add an OpenAPI referenceCopied!

Add an OpenAPI/Swagger file to your configuration file:

{
  "references": [
    {
      "name": "API Reference",
      "path": "docs/openapi.yaml"
    }
  ]
}

That’s it. :) The next time your documentation is published, it’ll include a super cool API reference.

Deploy on mergeCopied!

You can use the UI on https://dashboard.scalar.com or the Scalar configuration file to enable Publish on Merge, which – you might have guessed it — publishes your documentation when a branch is merged into the default branch (main):

{
  "publishOnMerge": true
}

Use a custom themeCopied!

You don’t like how the documentation looks? Just try a few of our themes:

{
  "theme": "purple"
}

Available themes:

• alternate
• default
• moon
• purple
• solarized
• bluePlanet
• deepSpace
• saturn
• kepler
• mars

Use a custom domainCopied!

Okay, this requires a subscription, but it’s pretty neat: You can add a custom domain to stay fully on brand and we’ll make sure to deploy your documentation, get a SSL certificate and all that.

{
  "customDomain": "docs.example.com"
}

Head to your domain name provider (Namecheap, GoDaddy, …) and add the following DNS records to the domain name you’d like to publish to: