Avo Docs runs on Node.js 18 or later. To get started developing clone the repository and run the following commands:
yarn # or "npm install"
yarn dev # or "npm run dev"Open 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. To add a new page, simply create a new .md or .mdx file inside the pages folder (or sub-folder depending on where in the navigation you want to have it).
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 Nextra and are deployed to Vercel. We recommend familiarizing yourself with the Next.js documentation before you get started developing.
- Nextra
- 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. You can do that by running yarn lint && yarn spellcheck && yarn avo status.
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 and it will be reflected in the navigation. To control the displaying and positioning in the navigation, edit the folders _meta.json file (see more in the Nextra docs)
The page's body is written in MDX, a markdown extension that allows you to embed React components.
To create links, simply use the standard markdown syntax. When linking to another docs page, you should skip the "/docs" part of the url. E.g. [Link to FAQ](/help/faq) will link to the FAQ page.
To add an image, add it to the public/images folder and then reference it using the standard markdown syntax. E.g. . Just as with links, you should skip the "/docs" part of the url.
Sometimes we like to put a page to a different place in the navigation hierarchy. You can do that by simply moving the file. As that changes the url, we need to make sure that old links end up in the new location by adding a re-direct to the next.config.js file.
To manually typecheck and lint your code run the following command:
yarn lint # runs Next.js's linting
To catch spelling errors we rely on cspell to set us straight. CI will use yarn spellcheck to check for any errors, as can any dev locally but sometimes cspell will not recognize some of our fancy developer speak. You might want to add a word to the dictionary in cspell.json to help it better understand.
yarn run spellcheck # Run spellcheck and gather errors