Project structure

A guide to setting up and organising files in a Basedoc project.

A Basedoc project needs to be organised into a few different directories and files.

To skip scaffolding by hand, fork basedoc-starter on GitHub, then link that repository when you create a project in Basedoc.

Project structure

A Basedoc project is a simple folder with a few files and directories.

my-project/
  media/
  <folder-for-content>/
    index.mdx
    <another-page>.mdx
  basedoc.json
  index.mdx
  <another-page>.mdx
  README.md

Config file

The basedoc.json file is used to configure the project's settings, including the project's title, navigation, theming and more.

Learn more about the config file.

The media directory is used to store any media files for your project, like logos, favicons, and images used in your documentation pages. All images and other media should be stored in this directory.

Organising your content

You can store your Markdown files anywhere in your project, but it's recommended to organise them in dedicated focused folders.

For example, if you have API docs, you can store them in a /api folder.

Pages will be given the URL that matches their file path. For example, a file at /api/get-users.mdx will have the URL /api/get-users.

Files you add to your project are not automatically added to the navigation so you have flexibility to organise your content as you see fit.

index vs named pages

index.md or index.mdx files inside directories will be given the URL of the directory.

For example, a page named /api/index.mdx will have the URL /api.

Also, a page named /api.mdx will have the URL /api.

It is up to you which you use, but it is usually easier to use a <folder>/index.mdx file.

Do not create both /api/index.mdx and /api.mdx, as this will cause issues with the navigation.

README.md

The README.md file is used to describe your project. It is not used by Basedoc but is very useful in GitHub and other version control systems.

It is a good idea to include a README.md file in your project, even if it is empty.

We recommend you at least explain how to set up and use Basedoc in this file, or give some instructions for your collaborators.

Project structure