Previous: Contribution guidelines | Next: Notes for Box employees
This project has a few prerequisites.
Git
to download the source code- When using Docker
- A local installation of Docker. I'd recommend the Docker Desktop on Mac.
- Docker Compose which can be
installed with
Homebrew
usingbrew install docker-compose
.
- When not using Docker
Node.js
for compilation and linting of the API specification. Ideally Node 18 or above.Yarn
is the Node package manager for this project. It can be installed withnpm i -g yarn
if Node is installed.YamlLint
is the linter to validateYaml
files. It can be installed withbrew install yamllint
if your machine hasHomebrew
installed.
To setup this project, download the source code and install all the dependencies.
git clone [email protected]:box/developer.box.com.git developer.box.com
cd developer.box.com
To run with Docker
docker-compose up --build
To run with Node directly, make sure you have Node 18 or higher installed.
yarn install
yarn start
With the dependencies installed, it is possible to lint the markdown and microocopy. Linting validates the markdown is valid, has no spelling mistakes, and that there are no obvious incorrect links.
yarn lint
Additionally, each of the lint steps can be run individually.
lint:markdown # runs markdownlint to validate the markdown syntax
lint:spelling:interactive # validates the spelling of the files
lint:alex # validates that none of the text includes any insensitive content
lint:yaml # validates that the microcopy files are valuid Yaml
lint:links # runs some basic linting on the links in the guides
Before the markdown and microcopy can be used in other projects they need to be transpiled.
yarn build
This build performs a few simple steps:
- It reformats the markdown to add extra spacing around HTML/React tags
- It turns self closing HTML tags (
<Foo />
) into sperate open and closing tags (<Foo></Foo>
) - It adds some extra information to each markdown file in the frontmatter
- it converts all the seperate microcopy Yaml files into one big JSONP file (JSON with comments).