Creating and updating pages in Gestalt

To add a new page, follow these 4 steps:

1. Create the page under the correct folder
   1. Regular page
      1. Create the new file in docs/pages
         1. The folder structure corresponds to the navigation structure of the site. For example, a new web component page should be created under docs/pages/web, and a new Tooling page should be found under docs/pages/get_started/developers/tooling
            1. The file path (and structure in docs/docs-components/siteIndex.js) create the URL path for the page, so both the file location and siteIndex structure must be accurate to get the expected URL
         2. Pages that do not fall under a main tab, like Roadmap, live at the root of docs/pages
   2. Markdown Page
      1. Create the file under the correct folder in docs/markdown
         1. The folder structure corresponds to the navigation structure of the site. For example, a new iOS component page should be created under docs/markdown/ios, and a new Tooling page should be found under docs/markdown/get_started/developers/tooling
2. Add the page name to docs/docs-components/siteIndex.js
   1. Find the appropriate section within the JSON object
3. Create an accessibility test for the new page in playwright/accessibility
   1. Create a file named [NEW PAGE TITLE].spec.mjs
      1. The file name should match the page name
      2. If the page is a duplicate (like Avatar on Web and Avatar on iOS), add a suffix with the platform, like Avatar_iOS.spec.mjs
4. Update docs/docs-components/COMPONENT_DATA.js
   1. If this is a net new component, you’ll need to add data under the correct array
      1. The options are Building Blocks, General Components, Utilities, Figma-only, and Foundation guidelines.
         1. This info affects the layout of the Component Overview page
      2. You may also need a new svg to represent this component on the Overview pages. Reach out on Slack if you need assistance with the graphic.
   2. If this is a new page for an existing component, like the Android page for an existing Web component, update the corresponding data for the object that already exists for that component. (See example)

When moving or deleting a page, there are multiple updates needed:

1. The organization of docs/docs-components/siteIndex.js
   1. Make sure the data stays in sync with your change
2. Any URLs within the docs or component pages referencing the page
   1. If you’re moving or deleting a page, update any references to that URL
3. Information in docs/docs-components/COMPONENT_DATA.js
   1. Ensure any updates are reflected in the JSON data
4. The associated spec.mjs accessibility test
   1. Update the URL or remove the file if deleting a page
5. List of redirects in docs/redirects.js
   1. A redirect must be added anytime a file is moved to help folks find the new location