Skip to main content

Installation

Welcome! This guide walks you through setting up docStatic for the first time.

If you’ve never worked with GitHub or docs-as-code before, don’t worry—we’ll explain what’s needed, why and where to find more detail.

Prerequisites​

You can run docStatic locally (on your computer) or host it in the cloud.

For the easiest cloud setup, create free accounts with these services:

  • GitHub—stores your content and tracks changes
  • TinaCMS—enables browser-based editing
  • LanguageTool—provides optional grammar and style checking

If you plan to run docStatic locally (on your computer) instead, see the Requirements for local development.

Requirements for local development​

This section only applies if you plan to work locally.

You'll need an Integrated Development Environment (IDE) or a text editor. Two open-source options are:

You will also need to install Node.js for its build tools and Yarn for package management.

Install Node.js​

You need to install Node.js version 22.0 or above.

Check if Node.js is already installed. Open a terminal (Command Prompt or Terminal app) and run:

node -v

If you see a version number starting with v22 or higher, you're good to go.

If Node.js is not installed or you have an older version:

  1. Go to the official Node.js downloads page.

  2. Choose the LTS (Long-Term Support) version for your operating system.

    The installer includes npm, the Node Package Manager, which you'll need in later steps.

    During installation:

    * Keep the default options selected (these include required dependencies) * When the installer finishes, close and reopen your terminal.

  3. (Optional) if you work on different projects that need different Node versions, install nvm (Node Version Manager). With nvm, you can switch between versions of Node without breaking your setup.

Install Yarn​

docStatic uses Yarn for package management.

Check if Yarn is already installed. Open your terminal or command prompt and type:

yarn -v

If you see a version number, Yarn is already installed.

If you get a “command not found” message or similar error, open a terminal (Command Prompt or Terminal app) and run:

npm install -g yarn
Note

On macOS or Linux, you might need to prefix the command with sudo to grant permission:

sudo npm install -g yarn
Note

On Windows, you don’t use sudo. Just open your terminal as Administrator and run the command.

Get docStatic​

There are two ways to get your own copy of docStatic:

  1. Create a new site with create-docstatic (recommended). One command gives you a fresh, standalone site with its own name and git history.
  2. Fork and clone the repository. Choose this if you want to contribute to docStatic itself, or prefer to manage updates by merging with git.

Create a new site​

Open a terminal (Command Prompt or Terminal app) and run one of the following commands, depending on your preferred package manager. Replace my-docs with the name of your project.

npx create-docstatic@latest my-docs

The command downloads the latest docStatic template, creates the my-docs folder, turns it into a git repository and installs the project dependencies. When it finishes, start the local development server:

cd my-docs
yarn dev
Tip

Run npx create-docstatic@latest --help to see the available options, such as --no-install to skip dependency installation.

If you created your site this way, you can skip ahead to the Project structure section.

Keep your site up to date​

When a new version of docStatic is released, run this command from the root folder of your site:

npx create-docstatic@latest --update

The command updates the docStatic-owned files (React components, build scripts, Docusaurus and Tina configuration, dependency versions) and leaves your content—docs/, blog/, config/, reuse/ and static/—untouched. Your site's name and any custom package.json scripts you added are preserved.

The update requires a clean git working tree, so commit your work first. Afterwards, review the result with git diff, reapply any customisations you had made to updated files and commit.

Tip

Add --dry-run to see what would change without writing anything.

Fork the docStatic repository​

Forking and cloning is the right choice if you plan to contribute to docStatic, or if you prefer to merge future docStatic releases into your site with git.

  1. Log in to your account in GitHub.
  2. Visit https://github.com/aowendev/docstatic.
  3. Click Fork (it is usually to the top-right).
  4. Leave the default Repository name in place.
  5. Enter a description of your project.
  6. Make sure Copy the main branch only is checked.
  7. Click Create fork.

GitHub makes a new branch of the repository in your GitHub account.

Clone your fork of the docStatic repository​

To create a clone:

  1. Log in to your GitHub account.
  2. Navigate to the repository for the fork.
  3. Click on the repository to open it.
  4. Click on <> Code and then copy the URL.
  5. Open your terminal or command prompt and use cd to navigate to the location where you want to store the clone. For example, cd Documents/Projects/.
  6. Enter git clone followed by the URL of your clone.
git clone https://github.com/acme-projects/docstatic.git

Install the project dependencies​

This step only applies if you forked and cloned the repository—create-docstatic installs the dependencies for you.

Use cd to navigate to the root folder of your cloned docStatic repository and install the packages:

cd docstatic
yarn install

Yarn will download everything listed in package.json. This may take a few minutes.

Project structure​

After creating your site or cloning the repository, you will see various files in your project folder. Below, we've included some of the project structure files and folders that you need to be aware of. It is not a complete list of everything in the project.

docstatic
├── apis
│   └── petstore.yaml
├── blog
│   └── hybrid.mdx
├── config
│   ├── docusaurus
│   │   └── index.json
│   ├── homepage
│   │   └── index.json
│   └── sidebar
│       └── index.json
│   
├── docs
│   └── introduction.mdx
├── i18n
│   └── fr
├── mcp-server
│   └── src
│       └── server.ts
├── reuse
│   ├── code
│   │   └── example.xml
│   ├── conditions
│   │   └── index.json
│   ├── glossaryTerms
│   │   └── index.json
│   ├── snippets
│   │   └── example.mdx
│   ├── taxonomy
│   │   └── index.json
│   ├── variableSets
│   │   └── index.json
│   ├── code-files.json
│   └── snippets-files.json
├── scripts
│   └── generate-media-index.js
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── example-page.mdx
│       ├── index.js
│       └── index.module.css
├── static
│   └── img
├── tina
│   └── config.jsx
├── docusaurus.config.ts
├── package.json
├── README.md
├── sidebars.ts
└── yarn.lock

Project structure rundown​

  • /apis/ - OpenAPI YAML files.
  • /blog/ - Blog MDX files.
  • /config/ - JSON files used by TinaCMS to configure docStatic.
  • /docs/ - Docs MDX files.
  • /i18n/ - Translation files.
  • /mcp-server/ - The MCP server that gives AI assistants access to your documentation.
  • /reuse/ - Reusable content.
  • /scripts/ - Build-time scripts run automatically by prebuild and predev.
  • /src/ - Non-documentation files like pages or custom React components.
    • /src/pages - Any JSX/TSX/MDX file within this directory are converted into a website page.
  • /static/ - Static folder. Any content inside here is copied into the root of the final build folder.
  • /tina/ - TinaCMS configuration and GraphQL schema.
  • /docusaurus.config.ts - A config file containing the site configuration.
  • /package.json - A docStatic website is a React app. You can install and use any npm packages you want.
  • /sidebars.ts - Specifies the order of documents in the sidebar. Use this for your “table of contents” structure.

Monorepos​

docStatic allows the use of a single repo that contains both the project code and the project documentation. In Docusaurus terminology, this concept is called a “monorepo”.

For more information, see Monorepos in the Docusaurus documentation.

Preview changes​

To preview your changes as you edit the files, you can run a local development server that will serve your website and reflect the latest changes.

Open a terminal or command prompt and enter:

yarn dev

By default, a browser window will open at http://localhost:3000.

Build​

docStatic uses a static site generator to build the website into a folder of static contents and put it on a web server where it can be viewed. To build the website, use:

yarn build-local

The contents are generated in the /build folder, which you can copy to any static file hosting service such as GitHub pages, Netlify or Vercel. For more information, refer to Deployment in the Docusaurus documentation.

Related topics

  • Introduction – docStatic was designed from the ground up to be easily installed and used to get your website up and running quickly.
  • Upgrading – Upgrading Node.js modules.
  • CLI – docStatic command line scripts.
  • Creating pages – Creating pages in the CMS.
  • Create a doc – Create a Markdown document.
  • Footnotes – Automatically numbered and back-linked footnotes.
  • Tabs – Using tabs in docStatic.