To get started developing clone the repository and run the following commands:
yarn
yarn devOpen http://localhost:3000 with your browser to see the result.
Each page lives in a separate file in the pages/ directory. Start editing and see the site update live in your browser.
This project uses TypeScript, ESLint and Prettier. We recommend configuring your editor so that it automatically formats your files using our config and displays type and linting errors inline.
The Avo docs are built using Next.js and are deployed to Vercel. We recommend familiarizing yourself with the Next.js documentation before you get started developing.
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
When you create a pull request it automatically gets linted, type checked and deployed to a Vercel preview URL. Before you submit a PR for review make sure your branch passes all checks and that the deployment looks good.
Each page in the docs lives in a file in the pages/ directory. This directory's folder structure dictates the application's routing. E.g. the file pages/help/faq.mdx will be accessible at http://avo.app/docs/help/faq.
The page's contents are preceded by YAML frontmatter. Here's an example from the getting started page:
---
layout: 'guide'
title: 'Getting started'
---
The layout and title properties are required. Layout specifies which layout the page should use and should match the filename of a .tsx file in the layouts/ directory. The title is displayed at the top of each page. Different layouts can support different frontmatter properties, so it can be helpful to take a look at the layout's source to see what's available.
The page's body is written in MDX, a markdown extension that allows you to embed React components. In most cases the only JSX you'll be embedding is <Link /> components. We support GitHub flavored markdown with a few extensions. When creating a new page we recommend looking at existing ones to get an idea of how we format our docs.
Take note:
The highest level heading we use in our pages is
##. This is to maintain proper hierarchy as the page title is rendered as an<h1 />element.
To manually typecheck and lint your code run the following command:
yarn run lint # Run ESLint and TSC
yarn run lint-mdx # Run MDXLint
To catch common errors and enforce consistency we've created an MDX linter. Under the hood it uses Remark and Remark MDX to parse your markdown. This is the same library that Next.js uses under the hood.
Each rule is a function with the following signature:
export type RuleFunction = (
node: Node,
metadata: {
filePath: string;
},
) => MDXError[];Where node is the root node of the parsed abstract syntax tree. The function should then run some checks on the tree, and return a list of MDXError objects. The rule is then registered in util/mdxLint/index.ts.
Take a look at some of the rules in the util/mdxLint/rules/ directory for inspiration.
To catch spelling errors we rely on mdspell to set us straight. CI will use yarn spellcheck to check for any errors, as can any dev locally but sometimes mdspell will not recognize some of our fancy developer speak. This is where using yarn fix-spelling comes in handy to deal with those situations, handily creating ignores for us globally or on page level.
yarn run spellcheck # Run spellcheck and gather errors
yarn run fix-spelling # Run spellcheck and fix errors one by one
We're using Algolia's free DocSearch. To update our scraping config send a pull request changing avo.json in the DocSearch config repo. The documentation search index is updated every 24 hours.