From 7509a7a48638b0b56b8fcc4ba5955bcf084cf6f7 Mon Sep 17 00:00:00 2001 From: Neill Robson Date: Thu, 13 Jun 2024 14:31:02 -0400 Subject: [PATCH] General README updates for readability --- README.md | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 3c71e84..be30796 100644 --- a/README.md +++ b/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); 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!