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 started
The following guide takes you from zero to deployed documentation in just a few minutes.
Set up your docs repository
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 Scalar
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 changes
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 configuration
There's definitely more to configure. Here are some more options for you:
Add an OpenAPI reference
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 merge
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 theme
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 domain
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:
Type | Host | Value |
---|---|---|
CNAME |
docs (if the domain is docs.example.com ) |
dns.scalar.com |