This website was created with Docusaurus.

• Get Started in 5 Minutes
• Directory Structure
• Editing Content
• Adding Content
• Updating the Documentation Following Changes in react-native-windows
• FAQ
• Full Documentation

1. Make sure all the dependencies for the website are installed:

# Install dependencies
$ yarn install

2. Run your dev server:

# Start the site
$ yarn start

Any changes you make to the markdown files under docs will be visible in the next version of the docs, i.e. http://localhost:3000/react-native-windows/docs/next/getting-started

Your project file structure should look something like this

my-docusaurus/
  docs/
    doc-1.md
    doc-2.md
    doc-3.md
  website/
    core/
    node_modules/
    pages/
    static/
      css/
      img/
    package.json
    sidebar.json
    siteConfig.js

Edit docs by navigating to docs/ and editing the corresponding document:

docs/doc-to-be-edited.md

---
id: page-needs-edit
title: This Doc Needs To Be Edited
---

Edit me...

For more information about docs, click here

Refer to the dedicated react-native-devblog (microsoft/react-native-devblog) repository for it - Microsoft internal only.

1. Create the doc as a new markdown file in /docs, example docs/newly-created-doc.md:

---
id: newly-created-doc
title: This Doc Needs To Be Edited
---

My new content here..

1. Refer to that doc's ID in an existing sidebar in website/sidebars.json:

// Add newly-created-doc to the Getting Started category of docs
{
  "docs": {
    "Getting Started": [
      "quick-start",
      "newly-created-doc" // new doc here
    ],
    ...
  },
  ...
}

For more information about adding new docs, click here

Refer to the dedicated react-native-devblog (microsoft/react-native-devblog) repository for it - Microsoft internal only.

1. Add links to docs, custom pages or external links by editing the headerLinks field of website/siteConfig.js:

website/siteConfig.js

{
  headerLinks: [
    ...
    /* you can add docs */
    { doc: 'my-examples', label: 'Examples' },
    /* you can add custom pages */
    { page: 'help', label: 'Help' },
    /* you can add external links */
    { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' },
    ...
  ],
  ...
}

For more information about the navigation bar, click here

1. Docusaurus uses React components to build pages. The components are saved as .js files in website/pages/en:
2. If you want your page to show up in your navigation header, you will need to update website/siteConfig.js to add to the headerLinks element:

website/siteConfig.js

{
  headerLinks: [
    ...
    { page: 'my-new-custom-page', label: 'My New Custom Page' },
    ...
  ],
  ...
}

For more information about custom pages, click here.

1. Submit code updates to react-native-windows main branch.
2. Submit documentation updates to this repo's main branch.
   1. Documents should be added/updated in docs
   2. Update sidebar contents in sidebars.json in website

1. Submit code updates to react-native-windows 0.XX-stable branch.
2. Submit documentation updates to this repo's main branch.
   1. Documents should be added/updated in version-0.XX folder under /website/versioned_docs.
   2. Update sidebar contents in version-0.XX-sidebars.json in /website/versioned_sidebars.

Complete the documentation updates for both main and stable version 0.XX above.

1. Update necessary version references in docs.

   1. getting-started.md - make sure to update from "nightly" to "latest" and change the previous stable version from "latest" to "0.XX-stable" in react-native init.

2. Follow the Integration into the react-native-windows-samples-repo steps to add the latest API documentation.

3. If win10-compat.md has changed since the last version cut, copy contents of docs/win10-compat.md:

   1. The oldest version of win10-compat.md in versioned_docs should be replaced with the one from docs. Make sure to adjust the page id to match the older version.
   2. Confirm all other old versions of win10-compat.md should be deleted.

4. Snapshot the website for version 0.XX:

   1. cd website
   2. yarn run version 0.XX
   3. yarn run fix-unbroken

   This will create a new directory of versioned docs, version-0.XX, in website/versioned_docs. This will preserve all documents currently in the docs directory and make them available as documentation for version 0.XX. For more information on versioning, click here.

5. Edit website/.unbroken_exclusions and add the line !versioned_docs/version-0.XX/native-api/*-api-windows*.md underneath the other versioned doc exclusions listed at the top of the file.

6. Update support.js and add/update the entry for the new version of React Native Windows with the correct release and Active Support Start Date X (ex: 6/27/22). Then make sure to edit the previous version's:

   1. Maintenance Start Date (set to the last day of the month that's 1 month out from X, ex: 7/31/22)
   2. End of Support Date (set to the last day of the month that's 2 months out from X, ex: 9/30/22)

7. When you are ready for your new docs to be the default documentation on the website, edit website/siteConfig.js to point to 0.XX for its defaultVersionShown constant.

When Docusaurus creates a versioned "snapshot" folder under versioned_docs, only the docs that have been created/modified since the last "snapshot" are copied in. Asset files are not copied, and relative links are not updated. When building the website, the tool has its own fallback for building all of the correct pages and resolving the relative links.

Basically, assets are not versioned and must be kept in the repo root's docs/assets folder, and for the docs, if a doc is not present for a specific version, the tool looks back to the previous snapshots until it finds it.

For more details, see Docusaurus Fallback Functionality.

First, make sure to read How do the versioned snapshots work?.

Now, if you need to update an existing doc, look through the previous snapshots (in descending order) until you find the previously versioned doc.

If the changes you need to make are relevant to all versions >= that previous version, then simply modify that doc so all versioned snapshots >= that previous version will see the same changes when the website is rebuilt.

However, let's say that the information in that doc was correct for that previous version, but the behavior has changed for later versions. You'll need to copy that doc into the first snapshot where the change is relevant, update its id at the top of the file, and make your changes there. Again, now all versioned snapshots >= that previous version will see the same changes when the website is rebuilt.

Furthermore, if the updates are still relevant for the next unreleased version, be sure to make those changes to the docs in the root docs folder as well.

First, make sure to read How do the versioned snapshots work?.

Now, unaware of how the snapshots are used, unbroken will just see missing files. To fix that, we have a fix-unbroken.js script in the website folder. Running it will update the .unbroken_exclusions file to ignore the "broken" links that will actually be working when the website is built.

You can run the script from the website folder with yarn run fix-unbroken.

If you're still seeing "File not found" errors (not warnings) after you've updated the .unbroken_exclusions file, then you have an actual missing file to resolve.

The most common problem are with asset files. Make sure that all asset files are present in the repo root's docs/assets folder, and that you use links relative to the root docs folder, i.e.: exactly assets/image.png, not ./assets/image.png, /docs/assets/image.png, etc.

Full documentation can be found on the website.