Repository files navigation

Development onyari involves updating the machinery that renders MDN contentor improving the structure and styling of the MDN UI (e.g. the styling of theheader). If you are more interested in contributing to the MDN content, youshould check out thecontent repo READMEinstead.

Before you can start working with Yari, you need to:

1. Installgit,Node.js, andYarn 1.

2. Forkthe MDNcontent andyari repositories using the Fork button onGitHub.

3. 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.gitgit clone https://github.com/[your_account]/yari.git

To run Yari locally, you'll first need to install its dependencies and build theapp locally. Do this like so:

cd yariyarn install

See thetroubleshooting section below if you run intoproblems.

Now copy the.env-dist file to.env:

cp .env-dist .env

If you followed the instructions above and cloned thecontent repo as asibling of youryari repo, theCONTENT_ROOT environment variable is alreadyset 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 requiredfiles, start the Yari web server running, and open it in your browser:

yarn devopen http://localhost:3000

If you prefer you can useyarn start, which will re-use any previouslycompiled files; this is "riskier" but faster.yarn dev always ensures thateverything is up-to-date.

Theyarn start command also starts a server with slightly different behavior —it doesn't automatically reload when its source code files change, so use withcaution.

See also ourreviewing guide for information on how toreview Yari changes.

Firstly, thank you for your interest in contributing to Yari! We do have a fewrequirements when it comes to pull requests:

1. Please make use of afeature branch workflow.
2. We prefer if you use theconventional commits format whenmaking pull requests.
3. Lastly, we require that all commits are signed. Please see the documentationabout signed commitsandhow to sign yourson GitHub.

Thank you for your understanding! We look forward to your contributions.

Periodically, the code and the content changes. Make sure you stay up-to-datewith something along the following lines (replaceyari-origin with whateveryou calledthe remote location of theoriginal yari repo):

git pull yari-origin mainyarnyarn dev

When you embark on making a change, do it on a new branch, for examplegit checkout -b my-new-branch.

All source code isMPL-2.0.

For content, see itslicense in themdn/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 catchissues 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 servethe MDN content found in thecontent repo.Each document is stored as anindex.md (recommended) orindex.html file thatcontains metadata presented as YAMLfront-matter followed bythe document source.

The builder converts these "source files" into "build files" using a CLI toolthat iterates over the files, builds the HTML, and lastly packages it up withthe front-end code, ready to be served as static files.

Theyarn start command encapsulates the front-end dev server (onhttp://localhost:3000) and theserver (onhttp://localhost:5042).

All the sub-commands ofyarn start can be broken down and run individually ifyou want to work more rapidly.

If you configure an environment variable calledEDITOR, either on your systemas a whole or in the root.env file, it can be used in the development serverto link to sources which, when clicked, open in your preferred editor/IDE. Forexample, 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 VSCode IDE (replacecode in the above command with a different text editor nameif needed, e.g.atom or whatever). To test it, view any document onhttp://localhost:3000 and click the "Open in your editor" button.

Theserver has two main jobs:

1. Simulate serving the site (e.g. from a server, S3 or a CDN).
2. Trigger builds of documents that haven't been built, by URL.

All JavaScript and TypeScript code needs to be formatted withprettier andit'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 ranyarn for the first time (yarn is an alias foryarn install)it automatically sets up agit pre-commit hook that useslint-staged — awrapper forprettier that checks only the files in the git commit.

If you have doubts about formatting, submit your pull request anyway. If youhave formatting flaws, thepull request checks should catch it.

We maintain the dependencies usingDependabot in GitHub but if you want tomanually upgrade them you can use:

yarn upgrade-interactive --latest

Theserver builds content automatically (on-the-fly) when you're viewingpages, 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

Everyindex.html becomes two files:

• index.html — a fully formed and complete HTML file
• index.json — the state information React needs to build the page in theclient

When 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 afull build.

More information about how to set flaws can be found indocs/envvars.md.

Essentially, the default is towarn about any flaw and you can see those flawswhen usinghttp://localhost:3000. For completed builds, all flaws are ignored.This makes the build faster and there's also no good place to display the flawsin a production-grade build.

In the future, we might make the default flaw levelerror instead. Thatmeans that any new edits to (or creation of) any document will break incontinuous integration if there's a single flaw and the onus will be on you tofix it.

The various formats and sizes of the favicon are generated from the filemdn-web-docs.svg in the repository root. This file is then converted tofavicons usingrealfavicongenerator.net. Togenerate new favicons, edit or replace themdn-web-docs.svg file and thenre-upload that to realfavicongenerator.net.

If you want to talk to us, ask questions, and find out more, join the discussionon theMDN Web Docs chat room onMatrix.

Some common issues and how to resolve them.

There are two options to resolve this.

1. Disable the watcher viaREACT_APP_NO_WATCHER

   echo REACT_APP_NO_WATCHER=true >> .env

2. Increasemax_user_watches:
   Seehttps://github.com/guard/listen#increasing-the-amount-of-inotify-watchers

We can't know for sure what's causing this error but speculate a bug in howyarn fails to resolve if certain@babel helper libs should install its ownsub-dependencies. A sure way to solve it is to run:

rm -fr node_modulesyarn install

The default server port:5042 might be in use by another process. To resolvethis, you can pick any unused port (e.g., 6000) and run the following:

echo SERVER_PORT=6000 >> .env

Download and install:

Microsoft Visual C++ Redistributable for Visual Studio 2019 (x86,ARM64 )

If you get errors while installing dependencies via yarn on a Mac, you may needto install some additional packages. Check the error message for the packagename causing the problem.

1. First, installbrew if you haven’t already

2. To fix problems withgifsicle:

   brew install automake autoconf libtool

3. To fix problems withpngquant-bin:

   brew install pkg-config

4. To fix problems withmozjpeg:

   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 tolibpng16.a depending on the version oflibpng you have installed.