What is docs.page? #
docs.page is an open source project which allows you to create instant documentation with zero configuration.
At Invertase, we have a lot of open source projects which usually require fairly in-depth documentation. In the past, we worked with documentation generators such as Docusaurus, which help to build feature rich documentation websites.
Existing documentation generators cover a lot of use cases, but they still need additional setup to function:
- Locally installing and setting up the generator into a new or existing repository.
- Deploying the generated documentation website to a hosting service and configuring domains.
- Ensuring the generator is kept up to date with new releases.
- Handling production & preview deployments via custom scripts/actions.
docs.page allows you to focus on writing documentation and not worry about such tasks.
What features does it have? #
- Configurable: Add your own logo, theme, analytics, navigation and more with a simple config file.
- Previewing: View the documentation of any branch, pull request or specific commit.
- GitHub Bot: Install our GitHub bot to automatically get a URL to pull request documentation previews.
- Components: Powered by MDX, use React components such as Tabs (useful for projects with multiple languages) directly in your docs.
- Search: Easily add full search support powered by DocSearch.
- Custom Domains: Serve your documentation using your own domain.
Other useful features include:
- Global variable injection (for managing common variables across the project).
- Displaying assets using GitHub.
- Dark/Light mode.
- Code block highlighting and content copying.
- Page redirects.
- Per-page metadata support via Frontmatter.
How does it work? #
You can access documentation for a repository by visiting a URL such as
https://docs.page/:organization/:name (or a custom domain).
The project will read the organization and name from the URL, and query the GitHub GraphQL API to retrieve the
.mdx file within
docs directory. Since documentation pages are generated on demand, we've added support for viewing the documentation
for branches, pull requests and specific commits; Simply prepend the reference to the name or your repository, e.g.
to target the
https://docs.page/:organization/:name~next - learn more about previewing.
To ensure documentation pages are performant, each page is server rendered, cached and invalidated every 30 seconds. To further improve initial load performance, you can pre-render your repository documentation.
How do I get started? #
It's super simple:
- Add a
docsdirectory to your GitHub repository.
- Create an
- Visit the URL for your repository (
Custom Domains #
Already bought a domain for your new project? docs.page supports custom domains out of the box. Simply point your domain with a CNAME record
to our proxy, add the repository to the
domains.json file and you're good to go.
Should I use docs.page? #
docs.page has been designed for fairly generic documentation websites which have many pages and common Markdown content. If your project requires a custom design, components or something bespoke it's probably best to look at other documentation generator solutions.
We're actively working on docs.page, which is already in use on projects such as Melos. There are loads of improvements we've got in mind, but it's already a great project to get started with.