@mdn/yari
Advanced tools
 
Development on yari involves updating the machinery that renders MDN content
or improving the structure and styling of the MDN UI (e.g. the styling of the
header). If you are more interested in contributing to the MDN content, you
should check out the content repo README
instead.
Before you can start working with Yari, you need to:
Fork the MDN content and yari repositories using the Fork button on GitHub.
Clone the forked repositories to your computer using the following commands
(replace [your account] with the account you forked the repositories to):
git clone https://github.com/[your_account]/content.git
git clone https://github.com/[your_account]/yari.git
To run Yari locally, you'll first need to install its dependencies and build the app locally. Do this like so:
cd yari
yarn install
See the troubleshooting section below if you run into problems.
Now copy the .env-dist file to .env:
cp .env-dist .env
If you followed the instructions above and cloned the content repo as a
sibling of your yari repo, the CONTENT_ROOT environment variable is already
set and Yari will be able to find the content it needs to render.
At this point, you can get started. Run the following lines to compile required files, start the Yari web server running, and open it in your browser:
yarn dev
open http://localhost:3000
If you prefer you can use yarn start, which will re-use any previously
compiled files; this is "riskier" but faster. yarn dev always ensures that
everything is up-to-date.
The yarn start command also starts a server with slightly different behavior —
it doesn't automatically reload when its source code files change, so use with
caution.
See also our reviewing guide for information on how to review Yari changes.
Firstly, thank you for your interest in contributing to Yari! We do have a few requirements when it comes to pull requests:
Thank you for your understanding! We look forward to your contributions.
Periodically, the code and the content changes. Make sure you stay up-to-date
with something along the following lines (replace yari-origin with whatever
you called the remote location of the
original yari repo):
git pull yari-origin main
yarn
yarn dev
When you embark on making a change, do it on a new branch, for example
git checkout -b my-new-branch.
All source code is MPL-2.0.
For content, see its license in the mdn/content repository.
yari runs on Linux in CI, and when building for Production.
We also support Windows and MacOS, however we don't aim to proactively catch issues with CI on those platforms. If bugs arise, we welcome issues being filed, or PRs being opened to fix them.
Yari does a number of things, the most important of which is to render and serve
the MDN content found in the content repo.
Each document is stored as an index.md (recommended) or index.html file that
contains metadata presented as YAML
front-matter followed by
the document source.
The builder converts these "source files" into "build files" using a CLI tool that iterates over the files, builds the HTML, and lastly packages it up with the front-end code, ready to be served as static files.
The yarn start command encapsulates the front-end dev server (on
http://localhost:3000) and the server (on http://localhost:5042).
All the sub-commands of yarn start can be broken down and run individually if
you want to work more rapidly.
$EDITORIf you configure an environment variable called EDITOR, either on your system
as a whole or in the root .env file, it can be used in the development server
to link to sources which, when clicked, open in your preferred editor/IDE. For
example, in the root of the repo you could run:
echo 'EDITOR=code' >> .env
Now clicking certain links will open files directly in the currently open VS
Code IDE (replace code in the above command with a different text editor name
if needed, e.g. atom or whatever). To test it, view any document on
http://localhost:3000 and click the "Open in your editor" button.
The server has two main jobs:
All JavaScript and TypeScript code needs to be formatted with prettier and
it's easy to test this with:
yarn prettier-check
And conveniently, if you're not even interested in what the flaws were, run:
yarn prettier-format
When you ran yarn for the first time (yarn is an alias for yarn install)
it automatically sets up a git pre-commit hook that uses lint-staged — a
wrapper for prettier that checks only the files in the git commit.
If you have doubts about formatting, submit your pull request anyway. If you have formatting flaws, the pull request checks should catch it.
We maintain the dependencies using Dependabot in GitHub but if you want to
manually upgrade them you can use:
yarn upgrade-interactive --latest
ngrokngrok allows you to start an HTTP proxy server from the
web into your Yari server. This can be useful for testing your current build
using external tools like BrowserStack, WebPageTest, or Google Translate, or to
simply show a friend what you're up to. Obviously it'll never be faster than
your uplink Internet connection but it should be fairly feature-complete.
yarn start in one terminalngrok executable with: /path/to/your/ngrok http 5042This will display something like this:
Session Status online
Account (Plan: Free)
Version 2.3.35
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://920ba2108da8.ngrok.io -> http://localhost:5042
Forwarding https://920ba2108da8.ngrok.io -> http://localhost:5042
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00
Now, take that "Forwarding" URL (https://920ba2108da8.ngrok.io in this
example) and share it.
The server builds content automatically (on-the-fly) when you're viewing
pages, but you can pre-emptively build all the content in advance if desired.
One potential advantage is that you can get a more complete list of all possible
"flaws" across all documents before you even visit them.
The most fundamental CLI command is:
yarn build
Every index.html becomes two files:
index.html — a fully formed and complete HTML fileindex.json — the state information React needs to build the page in the
clientWhen building you can enable specific "flaw checks" and their level of handling. Some flaws are "cosmetic" and some are more severe but they should never block a full build.
More information about how to set flaws can be found in docs/envvars.md.
Essentially, the default is to warn about any flaw and you can see those flaws when using http://localhost:3000. For completed builds, all flaws are ignored. This makes the build faster and there's also no good place to display the flaws in a production-grade build.
In the future, we might make the default flaw level error instead. That
means that any new edits to (or creation of) any document will break in
continuous integration if there's a single flaw and the onus will be on you to
fix it.
The various formats and sizes of the favicon are generated from the file
mdn-web-docs.svg in the repository root. This file is then converted to
favicons using realfavicongenerator.net. To
generate new favicons, edit or replace the mdn-web-docs.svg file and then
re-upload that to realfavicongenerator.net.
If you want to talk to us, ask questions, and find out more, join the discussion on the MDN Web Docs chat room on Matrix.
Some common issues and how to resolve them.
Error: ENOSPC: System limit for number of file watchers reachedThere are two options to resolve this.
Disable the watcher via
REACT_APP_NO_WATCHER
echo REACT_APP_NO_WATCHER=true >> .env
Increase max_user_watches:
See https://github.com/guard/listen#increasing-the-amount-of-inotify-watchers
Error: Cannot find module 'levenary'We can't know for sure what's causing this error but speculate a bug in how
yarn fails to resolve if certain @babel helper libs should install its own
sub-dependencies. A sure way to solve it is to run:
rm -fr node_modules
yarn install
Error: listen EADDRINUSE: address already in use :::5042The default server port :5042 might be in use by another process. To resolve
this, you can pick any unused port (e.g., 6000) and run the following:
echo SERVER_PORT=6000 >> .env
If you get errors while installing dependencies via yarn on a Mac, you may need to install some additional packages. Check the error message for the package name causing the problem.
First, install brew if you haven’t already
To fix problems with gifsicle:
brew install automake autoconf libtool
To fix problems with pngquant-bin:
brew install pkg-config
To fix problems with mozjpeg:
brew install libpng sudo ln -s /opt/homebrew/Cellar/libpng/1.6.40/lib/libpng16.a /usr/local/lib/libpng16.a
You may need to adjust the path to libpng16.a depending on the version of
libpng you have installed.
2.49.0 (2024-04-18)
FAQs
 
The npm package @mdn/yari receives a total of 4,789 weekly downloads. As such, @mdn/yari popularity was classified as popular.
We found that @mdn/yari demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.