Getting Started

docs.page reads files directly from your GitHub repository and uses them to generate a documentation website. This guide will walk you through the steps to get started with docs.page.

There are two core principles to keep in mind when working with docs.page:

• Every project requires a docs.json file at the root of the project.
• All documentation files are stored in a docs directory as .mdx files.

Quick Start

To get started, either use the CLI tool or manually create the required files.

npx @docs.page/cli init

{
  "name": "My Project",
  "description": "My awesome documentation."
}

---
title: Hello docs.page
---

# Welcome to docs.page

Previewing your documentation

Now your project has the requires docs.json configuration file and a sample docs/index.mdx page, we can now preview our documentation.

Head on over to https://docs.page/preview and select your project directory when prompted. This will generate a preview of your documentation:

TODO: Image

You can made modifications to your configuration and documentation in realtime and see the changes reflected in the preview. For more information on local preview mode, view the Local Preview documentation.

Updating your configuration

At present your documentation doesn't look too great, isn't very informative and probably doesn't feel like it belongs to your product or service. Let's fix that.

The docs.json file which has been created in your project root contains a number of configuration options which can be used to customize your documentation. The Configuration documentation contains a full list of available configuration options. For example, let's change the theme color of our documentation via the theme property:

{
  "theme": {
    "primary": "#ab47bc"
  }
}

We can also add a logo to our documentation by setting the logo property:

{
  "logo": {
    "light": "https://mycdn.com/awesome-logo.png",
    "dark": "https://mycdn.com/awesome-logo-dark.png"
  }
}

Adding more documentation pages

Each .mdx file created inside of the docs/ directory represents a new page in your documentation. You can create as many pages as you like, and even nest them inside of subdirectories. For example, let's create a new docs/usage.mdx file:

---
title: Usage
---

# How to use my project

When users vist the /usage page on your documentation site, they will see the content of this file. To create a nested page, you can create a subdirectory inside of the docs/ directory, for example docs/platforms/windows/index.mdx:

---
title: Windows Usage
---

# How to use my project on Windows

When users visit the /platforms/windows page on your documentation site, they will see the content of this file.

Writing content

All of your documentation pages are written in markdown, with the added ability to include useful visual components.

Markdown is a simple markup syntax, which allows you to write plain text which is transformed into usable HTML elements, such as headings, images, links and lists. For example, to create a heading in markdown, you can use the # symbol:

### This is a level 3 heading

This is some paragraph text which will be shown below the heading.

Additionally, docs.page exposes components to allow you to include more complex elements in your documentation. For example, to add an accordion to your documentation, you can use the Accordion component:

<Accordion>
  This is the content of the accordion which will be shown when the accordion is expanded.
</Accordion>

To learn more about writing your markdown content, view the documentation.

Publishing your documentation

Publishing documentation using docs.page is the same as publishing code via version control on GitHub.

Documentation is accessible using the owner and repository name of your GitHub repository. For example, if your repository is available at https://github.com/acme/my-project, your documentation will be available at https://docs.page/acme/my-project.

The 'default' branch of your repository (typically main or master) is used as the production branch for your documentation. When you push changes to this branch, your documentation will be updated automatically.

Live Previews

Whenever you make changes to your repository, either code and/or documentation, the GitHub reference for the change (for example a branch or commit sha) can be used to view the documentation at that point in time.

For example, to view the documentation at a specific commit, you can use the following URL:

https://docs.page/acme/my-project~COMMIT_SHA

To view the documentation for a specific branch, you can use the following URL:

https://docs.page/acme/my-project~BRANCH_NAME

To learn more about documentation previews, view the Live Previews documentation.