Uses Gatsby to build static site.

Prerequisite: get a local doc site's AST to work with

1. Set up snooty-parser
2. Clone a docs site, for example: git clone git@github.com:mongodb/docs-landing.git
3. Parse the docs site with snooty-parser:

poetry run snooty build ./path/to/docs-landing/ --output ./snooty-output/docs-landing.zip

NOTE: If you'd like to see the JSON output of the AST, you can use:

bsondump --pretty --outFile ./path/to/pretty.json ./path/to/file.bson

From this repo:

1. Install snooty deps
2. Set up .env to point to local AST
3. Run the site locally

Snooty uses artifactory that will need authentication to install some private npm packages. Update your local zsh variables in $~/.zshrc (in Windows %USERPROFILE%/.zshrc) to include the following

export NPM_BASE_64_AUTH=<BASE_64_API_KEY>
export NPM_EMAIL=<your.email@gmail.com>

Then, log in with your new NPM credentials:

npm login

Then, to install the package dependencies:

npm install --legacy-peer-deps

You'll need to set some environment variables in two separate files at the root of this directory for separate production/development environments. These variables let Snooty know where to look for your AST zip files, within DOP team's database. (You can also use local AST files.)

Snooty's develop stage uses the development environment. Your .env.development file should be as follows:

GATSBY_SNOOTY_DEV=true
GATSBY_NEXT_API_BASE_URL=https://docs-on-nextjs.netlify.app/api

The GATSBY_SNOOTY_DEV variable is what allows Gatsby to know that it should use the snooty branch name as part of the file paths. When not set, the file paths will use the value of GATSBY_PARSER_BRANCH. See pathing here

It should be set to true when working on snooty locally.

The GATSBY_NEXT_API_BASE_URL variable points to our production Nextjs app API.

Snooty's build and serve stages use the production environment. Your .env.production file should be as follows:

GATSBY_SNOOTY_DEV=true
GATSBY_NEXT_API_BASE_URL=https://docs-on-nextjs.netlify.app/api

1. Build the toc.json file in your local doc-mongodb-internal repo.
   • > cd docs-mongodb-internal/content/table-of-contents
   • > npm run build
2. Link your toc.json folder in your .env file, for example
   • UNIFIED_TOC_JSON_PATH=/path-to-docs-mongodb-internal/docs-mongodb-internal/content/table-of-contents/output/toc.json
3. Declare the path prefix for the content directory you built locally in snooty-parser. For example if you parsed cloud-docs your path prefix will be:
   • PATH_PREFIX='docs/atlas'
4. Set the feature flag to true. GATSBY_USE_UNIFIED_TOC=true
   • If you need to click around in the sidenav locally but can only load one site at a time, you can set GATSBY_UNIFIED_TOC_DEV_MODE=true. This makes L1s and showSubNavs non-linking, allowing you to traverse the TOC without navigating away.

Example .env file for Unified ToC Setup

GATSBY_USE_UNIFIED_TOC=true
GATSBY_UNIFIED_TOC_DEV_MODE=true
PATH_PREFIX='docs/drivers/node/current'
UNIFIED_TOC_JSON_PATH=/Users/bianca.laube/Documents/repos/docs-content-repos/docs-mongodb-internal/content/table-of-contents/output/toc.json

npm run develop

To build and serve the site, run the following commands: The serve command generates the site at a prefix ie. localhost:9000/<branch>/<docs-name>/<user>/<branch-name>/

$ npm run build
$ npm run serve

To debug server side:

node --nolazy node_modules/.bin/gatsby develop --inspect-brk

and connect a node debugger (ie. chrome developer tools)

Alternative to working with remote AST files, you can have a local zip file to build the site. This removes the need for previously mentioned env variables required for remote lookup GATSBY_SITE GATSBY_PARSER_USER and GATSBY_PARSER_BRANCH. Local zip file is an output of the parser

.env.development and .env.production:

GATSBY_MANIFEST_PATH=/path/to/zipped/ast/file.zip
GATSBY_SNOOTY_DEV=true

Smartling is only configured for our pre-production and production environments. To mock other locales locally, set the following in .env files:

GATSBY_LOCALE=zh-cn
COMMIT_HASH=zh-cn

• GATSBY_LOCALE is used to change the html element's lang property to any locale. This can be useful for mocking the lang property set by Smartling, and for constructing CSS selectors targetting specific languages.
• COMMIT_HASH can be used to prepend its value to the path prefix of the site when building and serving. This can be useful for mocking the /<local-code>/<path> pathnames for docs pages, and for testing out locale-related logic for pathnames.

When a commit is pushed, this automatically triggers a Netlify build on your branch. For every push, a deploy and deploy preview will be generated.

By default, the master branch of docs-landing will be parsed with the parser version specified in the Netlify.toml and built using your branch as the frontend. If you'd like to build a different site or branch or build with a different parser version, this can be easily done by just updating the values in the Netlify.toml accordingly. Don't forget to update the ORG_NAME to mongodb or 10gen depending on which org your repo belongs to!

Install libxml2 with brew install libxml2 on mac and apt-get install libxml2 on linux

Install mut and ensure that you have properly configured your Giza/AWS keys as defined here. Then, from root, run:

npm run build:clean:stage

⚠️ Note: This will promote the contents of your local public directory. Your instance in staging may break or be outdated if you haven't run npm run build before make stage.

We have configured an automatic release process using GitHub Actions that is triggered by npm-version. To release a version, you must have admin privileges in this repo.

⚠️ This process cannot be completed if the releaser's origin points to a fork.

⚠️ Please do not create new git tags directly through the GH UI or CLI. Doing so may result in a merge conflict or git tag error when performing the following instructions.

Then proceed as follows:

1. On the main branch, run git pull followed by npm ci.
2. Run npm version [major | minor | patch], using Semantic Versioning guidelines to correctly increment the version number. Keep the minor version consistent with snooty-parser versioning. GitHub Actions will create a new git tag and push it to GitHub.
3. Update the release draft found here using the automatically generated CHANGELOG.md and publish the release. Keep "pre-release" checked until version 1.0.0.

Tests can be run using:

npm test  # alias for npm run test

Unit tests are located in the tests/unit/ directory. To run only unit tests, use:

npm run test:unit

Jest includes configurations for running individual test suites:

npm test -- my-test   # or
npm test -- path/to/my-test.js

For more information, see the Jest CLI Options documentation, or run npm test -- --help.

Snapshots may require updates when making changes to snooty components

npm test -- -u

We use ESLint and Prettier to help with linting and style.

Our CI (via GitHub Actions) is configured to test for lint errors. To run this test locally and attempt to automatically fix errors:

npm run lint:fix

These errors must be fixed for the CI build to pass.

To format code using Prettier, run the following command:

npm run format:fix

We have set up a precommit hook that will format staged files. Prettier also offers a variety of editor integrations to automatically format your code.

The component factory filter process uses SWC to remove unused components from the ComponentFactory.js file. A custom plugin is used to perform this transformation, and it lives in the component-factory-transformer directory. This plugin is run when the npm run build command is executed.

To use the custom plugin, you'll first need to install Rust.

Once Rust is installed, you'll need to build the plugin. Change directory to component-factory-transformer, run cargo build && rustup target add wasm32-wasip1 if you haven't, and then run npm run prepublishOnly.

The USE_FILTER_BRANCH environment variable needs to be added in the .env.production file and set to true for this to work.

NOTE: This will modify the ComponentFactory.js file directly. To undo this, you can run git restore src/components/ComponentFactory.js to get the file back to its original state.

To perform a dry run i.e. the ComponentFactory.js file does not get updated, the FILTER_DRY_RUN property can be provided and set to true. This will log the resulting code that would have been written to the file only.

The Unified TOC requires the GATSBY_USE_UNIFIED_TOC feature flag to be enabled. This feature flag is temporary and will be removed once the Unified TOC is officially launched. Without this flag enabled, the legacy TOC will be displayed instead.

Additionally, the GATSBY_UNIFIED_TOC_DEV_MODE environment variable needs to be set to handle active link styling on 404 pages (pages that are not included in the build) within the Unified TOC navigation. Without this environment variable, active styling will not be applied correctly on 404 pages.

GATSBY_USE_UNIFIED_TOC can be added to your .env.development and both can be added to your .env.production file.

The GATSBY_UNIFIED_TOC_DEV_MODE environment variable is required for being able to click through the Sidenav with staying on your current content site.

• Local production builds (using npm run build and npm run serve)
• Preview builds

This environment variable forces all L1 and showSubNav links in the Unified TOC to not change pages and to only change the side navigation.

For preview builds, writers need to ensure this environment variable is added to their Netlify configuration.

React Gatsby Emotion mongodb/Realm LeafyGreen UI