This documentation site serves as the both the documentation and workbench for Paragon. Get started:
- Install dependencies
npm install
- Start the dev server
npm start
- Navigate to
http://localhost:8000/
which corresponds tosrc/pages/index.mdx
Edits made to react components in src/
will be hot-reloaded in this doc site.
- Create a separate SASS stylesheet with your theme in
src/scss
, e.g.src/scss/my-theme.scss
. - Add your theme to
theme-config.js
, e.g.
exports.THEMES = [
...,
// Provide configuration of your theme so that documentation site can pick it up
//
// label: Label of your theme which will appear in theme selector
// stylesheet: Name of your theme's stylesheet (without extension) which you created during the first step,
// it's assumed that stylesheet is located in 'src/scss'. The stylesheet will be compiled into CSS
// and placed into ./public/static directory under <stylesheet>.css name
{
label: 'My custom theme',
stylesheet: 'my-theme',
},
];
- Build your theme
-
If you have already started the dev server with
npm start
, runnpm run build-themes
the command will build your theme and add it to the site
-
If you haven't started the dev server yet, start it with
npm start
and your theme will automatically get picked up during the build.
Playground is a separate application (provided by playroom package) that in production gets bundled together with docs site and is served by Gatsby by rendering this application in an iframe on the /playground
route.
Currently, there is no way to reproduce this behavior in development mode. To work with Playground locally in development mode with hot-reloading you have to start playroom
's dev server and work with it separately from the docs site. To do that, run:
npm run playroom:start
which will make playroom
available at http://localhost:9000/.
To reproduce the production environment, you may build playroom
's production bundle and serve it with Gatsby:
npm run playroom:build
npm run serve
This will make docs site available at http://localhost:9000/ together with Playground page working as in production site.
In some scenarios, it is helpful to put your changes to the Paragon documentation site behind a feature flag so that you have more control over how a particular feature or change is rolled out more broadly.
To configure feature flags for the documentation site, see the file src/config.js
for instructions.
A feature flag may be enabled in two ways:
- Environment variable. This will allow you to persist the state of a feature flag at build time, with no way to disable it.
- Query parameter. Adding
?feature=
to the URL as a query parameter, you can temporarily enable one or more features.
Listed features below are set up in the doc site. Some features can be enabled by default. To disable a specific feature, don't pass anything to the corresponding variable.
Axe is an accessibility testing engine for websites and other HTML-based user interfaces. By default, it is enabled and controlled by FEATURE_ENABLE_AXE
. Open the console on a particular page on the site to see warning and errors from this package.
MDX is a flavor of Markdown that affords writing JSX directly inside markdown files. For more information visit the website: https://mdxjs.com/.
Syntax highlighting: