Remix Docs Template

A Remix starter template for running a markdown documentation site pulling from GitHub.

Features

• Remote fetching of markdown and images from GitHub
• Version selector
• Customisable components
• Configuration
• Cache support

Building Blocks

• Remix for the framework
• Vite for the build tool / compiler
• Tailwind CSS for styling
• Shadcn for the accessible, customisable, open-source components.

🖤 Acknowledgement

A special call out to the following for the inspiration and guidance and code that make up this template. Without them, this template would not have been created.

• Remix website
• Kent C Dodds

Support

• Join the discussion on the Boomerang Slack

Design

Routes

The docs path is based on a context of /docs/<language>/<branch>/<path>. The language will default to en and the branch will default to main. The path will be the path to the markdown or image file in the repository.

Redirects

There is a file called _redirects where you can put in paths for your documentation as things change.

Content

The content is pulled from a GitHub repository (or locally in development). The repository is expected to have markdown files and associated images. Images can be located relative or anywhere, as long as they are within the same 'pathToRepo' folder(s) as the markdown files.

Frontmatter

The markdown files can contain frontmatter as follows

---
title: A wonderful title | <string>
description: A detailed description | <string>
order: 1 | <number>
toc: true | false
hidden: true | false
tag: new | beta | <string>
---

If the documentation is within a folder, add an index.md file to the folder including the title and order frontmatter. This will then be used in the navigation.

Key	Type	Purpose	Required	Default
title	string	Used for the left hand document navigation and html site meta and seo.	yes	-
description	string	Used for the html site meta and seo.	no	-
order	string	Specify the order this doc should be shown within its category.	no	-
toc	boolean	Show or hide the table of contents.	no	true
hidden	boolean	Show or hide the file in the left hand document navigation	no	false
tag	string	A label to show next to the document title in the left hand document navigation.	no	-

Configuration

To provide as much flexibility as possible, inside the /app/config directory are multiple configuration files that control how this template functions. Read the individual configuration files for greater detail to the individual options.

• doc.ts - Controls the documentation and versioning integration.
• nav.ts - Controls the navigation and sidebar.
• site.ts - Controls general information displayed throughout the template such as title and description.

Additionally, there is a .env file that controls the environment variables for the template. This includes

Variable	Description	Required
GITHUB_TOKEN	A token to increase the rate limiting from 60/hr to 1000/hr	No
SOURCE_REPO	GitHub repo to pull docs from i.e. boomerang-io/docs	Yes
LOCAL_REPO_RELATIVE_PATH	For development, reading the docs from a local repo i.e. ../content	No
NO_CACHE	Turn off the cache for development	No

Setup

1. Copy the .env.example file and duplicate it to .env
2. Fill in the required configuration options in the .env file
3. Update the configuration files in the /app/config directory
4. Run pnpm install to install the dependencies

Development

Run the Vite dev server

pnpm run dev

Deployment

First, build your app for production:

pnpm run build

Then run the app in production mode:

pnpm start

Now you'll need to pick a host to deploy it to.