General README updates for readability

README.md

@@ -6,6 +6,13 @@
 
 ## Project setup
 
+> [!TIP]
+> **Just making a small change?** Try editing [directly in Github](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files)! You won't need to clone the repository or set up a local development environment.
+>
+> See the linked Github documentation for how to edit! Be sure to **create a new branch** and pull request so that your changes can be reviewed.
+
+*For engineers*:
+
 To run the site locally, you must have NodeJS and NPM installed.
 
 Additionally, you must have authenticated yourself in Artifactory, and associated the `@pendo` package scope to our private registry. Instructions for how to do so are on [Confluence](https://pendo-io.atlassian.net/wiki/spaces/ENG/pages/1437761584/JFrog+Artifactory+-+Private+NPM+Registry+Setup).
@@ -49,11 +56,12 @@ For example, a file called `icons.mdx` in the directory `src/content/foundations
 There are a couple of exceptions:
 
 - If the file is named `index.mdx` specifically, it will be dropped from the URL: `src/content/components/buttons/index.mdx` is rendered at a URL like `http://localhost:8080/prism-design-system/components/buttons`.
-- A file with a `META.tab` field set will only be rendered in a _tab_ (not a standalone page). See the "Tabs" section of the README for details.
+- A file with a `META.tab` field set will only be rendered in a _tab_ (not a standalone page). See the ["Tabs" section of the README](#tabs) for details.
 
 ### Sidebar Navigation
 
-**The sidebar is *not* currently auto-generated**. After creating new files, the URLs will be valid, but the links need to be manually added to `src/components/SidebarNav.vue`. Simply copy-pasting existing links and sections within that file's `template` section should be sufficient. No adjustments to the `script` or `style` should be necessary.
+> [!IMPORTANT]
+> **The sidebar is *not* currently auto-generated**. After creating new files, the URLs will be valid, but the links need to be manually added to `src/components/SidebarNav.vue`, in the `NAV_ITEMS` array. Simply copy-pasting existing links and sections in that variable should be sufficient.
 
 ### MDX Content
 
@@ -97,7 +105,8 @@ export const count = ref(0);
 <PendoButton label={`Count: ${count.value}`} onClick={() => count.value++} />
 ```
 
-**Documentation with heavy logic should be the exception, rather than the rule**. Use the above syntax only when absolutely necessary, and look for ways to simplify examples to be purely visual. The purpose of this documentation is **not** to demonstrate full-fledged application snippets: look to Storybook for those examples.
+> [!CAUTION]
+> **Documentation with heavy logic should be the exception, rather than the rule**. Use the above syntax only when absolutely necessary, and look for ways to simplify examples to be purely visual. The purpose of this documentation is **not** to demonstrate full-fledged application snippets: look to Storybook for those examples.
 
 ### Tabs
 
@@ -155,21 +164,26 @@ You will also be given a link to the deployment at the bottom of the PR discussi
 
 ![screenshot of GitHub deployment message on a pull request](./docs/deployment.png)
 
-Merges to `main` are protected:
-
-- The branch needs an open pull request
-- The `build` job needs to pass on that branch
-
-Once both of those conditions are met, merging can take place in either the Github UI, or on the command line.
+> [!WARNING]
+> Merges to the `main` branch **automatically trigger the site's deployment** to Github Pages. Therefore, a handful of conditions are enforced on branches before they can merge into `main`:
+>
+> - The branch needs an open pull request
+> - The `build` job needs to pass on that branch
+>
+> Once both of those conditions are met, merging can take place in either the Github UI, or on the command line.
 
-Merges to the `main` branch automatically trigger the site's deployment to Github Pages. Within a minute or two, the latest changes should be visible at `https://pendo-io.github.io/prism-design-system`.
+ Within a minute or two after merging into the `main` branch, the latest changes should be visible at `https://pendo-io.github.io/prism-design-system`.
 
 ## To Do
 
-The following items were stretch goals for Carrie and Neill during the 25.1 hackathon that were not completed:
+The best way to contribute is to **migrate documentation from Figma into the site!** If you see any pages that need updating (or creation), don't hesitate to give it a shot.
+
+Additionally, the following items were stretch goals for Carrie and Neill during the 25.1 hackathon that were not completed:
 
 - [ ] Flesh out the homepage with search bar and links to top-level pages. Figma designs for the homepage are [here](https://www.figma.com/design/VvIdJrQwAiip94MOReeghV/%F0%9F%8C%88-2024-Prism-Site?node-id=1105-7744&t=4Ieo0YmZOyIwBtwZ-4).
+
   This unit of work won't make sense to complete until there is content in the top-level pages (such as "About Prism", "Product design principles", etc).
+
 - [x] Implement the search bar functionality on the sidebar
 - [ ] Automatic generation of links in the sidebar based on URL routes
 - [ ] Auto-expand the sidebar sections to the currently-active route
@@ -179,5 +193,3 @@ The following items were stretch goals for Carrie and Neill during the 25.1 hack
   - [x] Lookaside links posted in a Github PR comment
   - [x] Automatic deployment of the `main` branch
 - [ ] Content Management System: some editor like [Prose](https://prose.io/) allowing for WYSIWYG editing of site content, with live previews
-
-Most importantly, **the site needs much of the documentation currently in Figma migrated into it!** If you see any pages that need updating (or creation), don't hesitate to give it a shot!