{"id":13406755,"url":"https://github.com/mdn/yari","last_synced_at":"2025-05-13T19:16:02.779Z","repository":{"id":36970276,"uuid":"188113049","full_name":"mdn/yari","owner":"mdn","description":"The platform code behind MDN Web Docs","archived":false,"fork":false,"pushed_at":"2025-05-12T12:21:37.000Z","size":147887,"stargazers_count":1235,"open_issues_count":195,"forks_count":528,"subscribers_count":40,"default_branch":"main","last_synced_at":"2025-05-12T12:45:10.751Z","etag":null,"topics":["mdn","yari"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mdn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-05-22T21:00:31.000Z","updated_at":"2025-05-12T12:20:36.000Z","dependencies_parsed_at":"2023-09-26T16:38:30.378Z","dependency_job_id":"e013bac0-f8e5-43f0-9f2b-965fc5fae246","html_url":"https://github.com/mdn/yari","commit_stats":{"total_commits":6312,"total_committers":166,"mean_commits":"38.024096385542165","dds":0.5619455006337135,"last_synced_commit":"f2bd8675b4ad5555c2ac33969e838178c031c0e7"},"previous_names":[],"tags_count":2697,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fyari","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fyari/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fyari/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fyari/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mdn","download_url":"https://codeload.github.com/mdn/yari/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010822,"owners_count":21999002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mdn","yari"],"created_at":"2024-07-30T19:02:38.459Z","updated_at":"2025-05-13T19:15:57.649Z","avatar_url":"https://github.com/mdn.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","JavaScript","others","Official resources"],"sub_categories":[],"readme":"# Yari\n\n![Testing](https://github.com/mdn/yari/workflows/Testing%20Yari/badge.svg)\n![Prod Build](https://github.com/mdn/yari/workflows/Prod%20Build/badge.svg)\n\n## Quickstart\n\nDevelopment on `yari` involves updating the machinery that renders MDN content\nor improving the structure and styling of the MDN UI (e.g. the styling of the\nheader). If you are more interested in contributing to the MDN content, you\nshould check out the [content](https://github.com/mdn/content) repo README\ninstead.\n\nBefore you can start working with Yari, you need to:\n\n\u003c!-- Peterbe, Feb 2021: There appears to be a bug in Prettier for .md files\n    that forces in a second (extra) whitespace after the `1.` here.\n    That breaks `markdownlint` *and* `prettier --check`. Annoying.\n    So for now let's make an exception. --\u003e\n\u003c!-- markdownlint-disable list-marker-space --\u003e\n\n1.  Install [git](https://git-scm.com/), [Node.js](https://nodejs.org), and\n    [Yarn 1](https://classic.yarnpkg.com/en/docs/install).\n\n1.  [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo)\n    the MDN [content](https://github.com/mdn/content) and\n    [yari](https://github.com/mdn/yari) repositories using the Fork button on\n    GitHub.\n\n1.  Clone the forked repositories to your computer using the following commands\n    (replace `[your account]` with the account you forked the repositories to):\n\n        git clone https://github.com/[your_account]/content.git\n        git clone https://github.com/[your_account]/yari.git\n\n\u003c!-- markdownlint-enable list-marker-space --\u003e\n\nTo run Yari locally, you'll first need to install its dependencies and build the\napp locally. Do this like so:\n\n    cd yari\n    yarn install\n\nSee the [troubleshooting](#troubleshooting) section below if you run into\nproblems.\n\nNow copy the `.env-dist` file to `.env`:\n\n    cp .env-dist .env\n\nIf you followed the instructions above and cloned the `content` repo as a\nsibling of your `yari` repo, the `CONTENT_ROOT` environment variable is already\nset and Yari will be able to find the content it needs to render.\n\nAt this point, you can get started. Run the following lines to compile required\nfiles, start the Yari web server running, and open it in your browser:\n\n    yarn dev\n    open http://localhost:3000\n\nIf you prefer you can use `yarn start`, which will re-use any previously\ncompiled files; this is \"riskier\" but faster. `yarn dev` always ensures that\neverything is up-to-date.\n\nThe `yarn start` command also starts a server with slightly different behavior —\nit doesn't automatically reload when its source code files change, so use with\ncaution.\n\nSee also our [reviewing guide](docs/REVIEWING.md) for information on how to\nreview Yari changes.\n\n### Pull request requirements\n\nFirstly, thank you for your interest in contributing to Yari! We do have a few\nrequirements when it comes to pull requests:\n\n1. Please make use of a\n   [feature branch workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow).\n2. We prefer if you use the\n   [conventional commits format](https://www.conventionalcommits.org/) when\n   making pull requests.\n3. Lastly, we require that all commits are signed. Please see the documentation\n   [about signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)\n   and\n   [how to sign yours](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)\n   on GitHub.\n\nThank you for your understanding! We look forward to your contributions.\n\n### How to stay up-to-date\n\nPeriodically, the code and the content changes. Make sure you stay up-to-date\nwith something along the following lines (replace `yari-origin` with whatever\nyou called [the remote location](https://git-scm.com/docs/git-remote) of the\noriginal yari repo):\n\n    git pull yari-origin main\n    yarn\n    yarn dev\n\nWhen you embark on making a change, do it on a new branch, for example\n`git checkout -b my-new-branch`.\n\n## License\n\nAll source code is [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/).\n\nFor content, see its\n[license](https://github.com/mdn/content/blob/main/LICENSE.md) in the\n[mdn/content repository](https://github.com/mdn/content).\n\n## Supported Platforms\n\n`yari` runs on Linux in CI, and when building for Production.\n\nWe also support Windows and MacOS, however we don't aim to proactively catch\nissues with CI on those platforms. If bugs arise, we welcome issues being filed,\nor PRs being opened to fix them.\n\n## How it works\n\nYari does a number of things, the most important of which is to render and serve\nthe MDN content found in the [content repo](https://github.com/mdn/content).\nEach document is stored as an `index.md` (recommended) or `index.html` file that\ncontains metadata presented as YAML\n[front-matter](https://github.com/mdn/content#fundamental-concepts) followed by\nthe document source.\n\nThe builder converts these \"source files\" into \"build files\" using a CLI tool\nthat iterates over the files, builds the HTML, and lastly packages it up with\nthe front-end code, ready to be served as static files.\n\n## Development\n\nThe `yarn start` command encapsulates the front-end dev server (on\n\u003chttp://localhost:3000\u003e) and the `server` (on \u003chttp://localhost:5042\u003e).\n\nAll the sub-commands of `yarn start` can be broken down and run individually if\nyou want to work more rapidly.\n\n### Setting up `$EDITOR`\n\nIf you configure an environment variable called `EDITOR`, either on your system\nas a whole or in the root `.env` file, it can be used in the development server\nto link to sources which, when clicked, open in your preferred editor/IDE. For\nexample, in the root of the repo you could run:\n\n    echo 'EDITOR=code' \u003e\u003e .env\n\nNow clicking certain links will open files directly in the currently open VS\nCode IDE (replace `code` in the above command with a different text editor name\nif needed, e.g. `atom` or whatever). To test it, view any document on\n\u003chttp://localhost:3000\u003e and click the \"Open in your editor\" button.\n\n### How the server works\n\nThe `server` has two main jobs:\n\n1. Simulate serving the site (e.g. from a server, S3 or a CDN).\n2. Trigger builds of documents that haven't been built, by URL.\n\n### Linting\n\nAll JavaScript and TypeScript code needs to be formatted with `prettier` and\nit's easy to test this with:\n\n    yarn prettier-check\n\nAnd conveniently, if you're not even interested in what the flaws were, run:\n\n    yarn prettier-format\n\nWhen you ran `yarn` for the first time (`yarn` is an alias for `yarn install`)\nit automatically sets up a `git` pre-commit hook that uses `lint-staged` — a\nwrapper for `prettier` that checks only the files in the git commit.\n\nIf you have doubts about formatting, submit your pull request anyway. If you\nhave formatting flaws, the\n[pull request checks](https://github.com/features/actions) should catch it.\n\n### Upgrading Packages\n\nWe maintain the dependencies using `Dependabot` in GitHub but if you want to\nmanually upgrade them you can use:\n\n    yarn upgrade-interactive --latest\n\n## Building\n\nThe `server` builds content automatically (on-the-fly) when you're viewing\npages, but you can pre-emptively build all the content in advance if desired.\nOne potential advantage is that you can get a more complete list of all possible\n\"flaws\" across all documents before you even visit them.\n\nThe most fundamental CLI command is:\n\n    yarn build\n\n### What gets built\n\nEvery `index.html` becomes two files:\n\n- `index.html` — a fully formed and complete HTML file\n- `index.json` — the state information React needs to build the page in the\n  client\n\n### Flaw checks\n\nWhen building you can enable specific \"flaw checks\" and their level of handling.\nSome flaws are \"cosmetic\" and some are more severe but they should never block a\nfull build.\n\nMore information about how to set flaws can be found in `docs/envvars.md`.\n\nEssentially, the default is to _warn_ about any flaw and you can see those flaws\nwhen using \u003chttp://localhost:3000\u003e. For completed builds, all flaws are ignored.\nThis makes the build faster and there's also no good place to display the flaws\nin a production-grade build.\n\n**In the future**, we might make the default flaw level `error` instead. That\nmeans that any new edits to (or creation of) any document will break in\ncontinuous integration if there's a single flaw and the onus will be on you to\nfix it.\n\n## Icons and logos\n\nThe various formats and sizes of the favicon are generated from the file\n`mdn-web-docs.svg` in the repository root. This file is then converted to\nfavicons using [realfavicongenerator.net](https://realfavicongenerator.net/). To\ngenerate new favicons, edit or replace the `mdn-web-docs.svg` file and then\nre-upload that to realfavicongenerator.net.\n\n## Contact\n\nIf you want to talk to us, ask questions, and find out more, join the discussion\non the\n[MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on\n[Matrix](https://wiki.mozilla.org/Matrix).\n\n## Troubleshooting\n\nSome common issues and how to resolve them.\n\n### `Error: ENOSPC: System limit for number of file watchers reached`\n\nThere are two options to resolve this.\n\n1. Disable the watcher via\n   [`REACT_APP_NO_WATCHER`](docs/envvars.md#react_app_no_watcher)\n\n   `echo REACT_APP_NO_WATCHER=true \u003e\u003e .env`\n\n2. Increase `max_user_watches`:\\\n   See \u003chttps://github.com/guard/listen#increasing-the-amount-of-inotify-watchers\u003e\n\n### `Error: Cannot find module 'levenary'`\n\nWe can't know for sure what's causing this error but speculate a bug in how\n`yarn` fails to resolve if certain `@babel` helper libs should install its own\nsub-dependencies. A sure way to solve it is to run:\n\n    rm -fr node_modules\n    yarn install\n\n### `Error: listen EADDRINUSE: address already in use :::5042`\n\nThe default server port `:5042` might be in use by another process. To resolve\nthis, you can pick any unused port (e.g., 6000) and run the following:\n\n    echo SERVER_PORT=6000 \u003e\u003e .env\n\n### Problems running with rari on Windows\n\nDownload and install:\n\nMicrosoft Visual C++ Redistributable for Visual Studio 2019 (\n[x86](https://aka.ms/vs/16/release/VC_redist.x86.exe),\n[ARM64](https://aka.ms/vs/16/release/VC_redist.arm64.exe) )\n\n### Yarn install errors\n\nIf you get errors while installing dependencies via yarn on a Mac, you may need\nto install some additional packages. Check the error message for the package\nname causing the problem.\n\n1. First, install [brew](https://brew.sh/) if you haven’t already\n\n1. To fix problems with `gifsicle`:\n\n   brew install automake autoconf libtool\n\n1. To fix problems with `pngquant-bin`:\n\n   brew install pkg-config\n\n1. To fix problems with `mozjpeg`:\n\n   brew install libpng sudo ln -s\n   /opt/homebrew/Cellar/libpng/1.6.40/lib/libpng16.a /usr/local/lib/libpng16.a\n\nYou may need to adjust the path to `libpng16.a` depending on the version of\n`libpng` you have installed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdn%2Fyari","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdn%2Fyari","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdn%2Fyari/lists"}