From 265b2ea91a06966d60109e6c263836a8505e87ed Mon Sep 17 00:00:00 2001 From: Nishant Arora <1895906+whizzzkid@users.noreply.github.com> Date: Thu, 27 Apr 2023 23:28:49 -0600 Subject: [PATCH] feat(docs): :memo: Adding image/video support in documentation --- User Guide.md | 34 +++++++------ next.config.js | 4 +- package.json | 4 +- pages/index.tsx | 13 ++++- yarn.lock | 131 ++++++++++++++++++++++++++++++++++++++++++++---- 5 files changed, 159 insertions(+), 27 deletions(-) diff --git a/User Guide.md b/User Guide.md index bab0a26f..c46776ff 100644 --- a/User Guide.md +++ b/User Guide.md @@ -1,5 +1,9 @@ # Starmap User Guide + + + + Starmap is a tool used to generate graphical representations of project roadmaps from GitHub issues. For the purposes of Starmap, a roadmap is represented by a single root node issue in GitHub that contains links to date-bound project milestone issues within that roadmap. The goal of Starmap is to help externalize planning, share team progress against milestones, and publicly flag dependencies. Starmap roadmaps are inter-team and user-focused. The tool provides flexibility in terms of the level of granularity that can be viewed, enabling users to drill down into specific details or see a high-level overview of the project as a whole. @@ -11,13 +15,13 @@ For more context around roadmapping within the Protocol Labs Network, watch the To render a roadmap in Starmap, enter the related GitHub issue URL into the Starmap search bar. Depending on the size of the roadmap, the rendering may take a minute to load. - Project milestones will appear as fixed-width cards on the Starmap timeline. - - If a milestone contains one or more nested “child” milestones, users can click on the milestone card to view that milestone and its nested child milestone(s). - - When applicable, Milestone cards will feature a green progress bar that reflects the completion status of nested child milestones. - - To access the source GitHub issue for any milestone, users can click on the GitHub icon within each milestone card. + - If a milestone contains one or more nested “child” milestones, users can click on the milestone card to view that milestone and its nested child milestone(s). + - When applicable, Milestone cards will feature a green progress bar that reflects the completion status of nested child milestones. + - To access the source GitHub issue for any milestone, users can click on the GitHub icon within each milestone card. - Starmap offers two rendering modes that can be set through the toggle button above the timeline: - - **Overview** mode displays high-level milestones plotted against a timeline. - - **Detailed view** mode organizes milestones under their respective parent milestones. - - **List view** will soon be added. + - **Overview** mode displays high-level milestones plotted against a timeline. + - **Detailed view** mode organizes milestones under their respective parent milestones. + - **List view** will soon be added. GitHub issues that do not satisfy the requirements for rendering in Starmap as outlined herein may not display correctly. To add your roadmap to GitHub in a manner that will allow it to render in Starmap.site, please refer to the section titled [Storing Roadmaps in GitHub](#storing-roadmaps-in-github). @@ -32,7 +36,6 @@ The fundamental unit of a roadmap is a project milestone. In the context of road - For more information on this, see the [Roadmap Root Nodes](#roadmap-root-nodes) section below. - Starmap allows you to easily create new roadmap visualizations by creating a new root "roadmap" node in GitHub that points to a set of existing milestones. This means that the same milestone can be included in multiple roadmaps. - ## Storing Roadmaps in Github ### Fundamentals @@ -60,12 +63,13 @@ ETA: YYYY-MM-DD Example: 2023-02-01 ``` + - If you are linking to an existing GitHub issue as a milestone, you must edit the issue to include an ETA. #### Issue Title - The titles of the Roadmap root node and milestone issues will be displayed in the Starmap visualization. - - You should appropriately title your issues to give users a clear picture of the roadmap content. + - You should appropriately title your issues to give users a clear picture of the roadmap content. - Issue titles are encoded as follows: ``` @@ -110,7 +114,7 @@ Tasklists allow for "taskifying" of strings, and we have no way to link a random We will do our best to support the expected syntax of GitHub's tasklist functionality. -See https://docs.github.com/en/issues/tracking-your-work-with-issues/about-tasklists#creating-tasklists and https://github.com/pln-planning-tools/Starmap/issues/245 for more details. +See and for more details. ``` ```[tasklist] @@ -123,7 +127,7 @@ See https://docs.github.com/en/issues/tracking-your-work-with-issues/about-taskl ##### "Children:" syntax -This syntax is deprecated. Please see https://github.com/pln-planning-tools/Starmap/issues/245 for more details. +This syntax is deprecated. Please see for more details. ``` Children: @@ -135,7 +139,7 @@ Children: ### Progress Indicators - Starmap shows progress against completion of every Milestone rendered within each milestone card. - - It uses the GitHub status (open/closed) of the children and the Roadmap root node itself to calculate progress. + - It uses the GitHub status (open/closed) of the children and the Roadmap root node itself to calculate progress. - As issues are resolved and closed, they are counted as progress towards completion. - Once all children and the parent node itself are closed, the progress bar on the parent will show 100% complete. @@ -145,11 +149,10 @@ Children: - Roadmaps with numerous milestones may not render in a useful way; it is recommended to have <= 5 milestones at any level. This is also a general best practice for project roadmaps. - Starmap’s two rendering modes (Overview and Detailed View) allow for the display of a roadmap in which there are multiple independent streams of delivery - which could be considered "themes", "pillars", etc. - - To do this, set up a root roadmap issue, where the theme issues are the children. - - Then, each child theme issue (encoded as a milestone), will be required to have an ETA. ETA should be set to the latest milestone ETA within that theme. + - To do this, set up a root roadmap issue, where the theme issues are the children. + - Then, each child theme issue (encoded as a milestone), will be required to have an ETA. ETA should be set to the latest milestone ETA within that theme. - The children of each theme are milestones; these are what get rendered under the theme headings in the timeline. - ### Templates #### Root Node Issue @@ -184,7 +187,7 @@ Starmap Link: [Starmap Link] ##### Using "Children:" -**NOTE:** The children: section is deprecated. Please see https://github.com/pln-planning-tools/Starmap/issues/245 for more details +**NOTE:** The children: section is deprecated. Please see for more details ``` Title: [Team/Project Name] [Duration] Roadmap @@ -204,6 +207,7 @@ Starmap Link: [Starmap Link] ``` #### Child Milestone Issues + ``` Title: [Team/Project Name] [Milestone Title] diff --git a/next.config.js b/next.config.js index 524542cd..d4fd97f4 100644 --- a/next.config.js +++ b/next.config.js @@ -14,7 +14,9 @@ const nextConfig = { dangerouslyAllowSVG: true, }, productionBrowserSourceMaps: true, - + images: { + domains: ['cdn.loom.com'], + }, webpack(config) { config.experiments = config.experiments || {}; config.experiments.topLevelAwait = true; diff --git a/package.json b/package.json index eb6b7fb2..f00f5114 100644 --- a/package.json +++ b/package.json @@ -51,7 +51,9 @@ "react-dom": "^18.2.0", "react-input-slider": "^6.0.1", "react-is": "^18.2.0", - "react-markdown": "^8.0.3", + "react-markdown": "8.0.7", + "rehype-raw": "^6.1.1", + "rehype-sanitize": "^5.0.1", "remark-gfm": "^3.0.1", "styled-components": "^5.3.6", "web-vitals": "^3.1.1", diff --git a/pages/index.tsx b/pages/index.tsx index ad220e54..8415fa08 100644 --- a/pages/index.tsx +++ b/pages/index.tsx @@ -3,6 +3,8 @@ import { join } from 'path'; import type { NextPage } from 'next'; import ReactMarkdown from 'react-markdown'; +import rehypeRaw from 'rehype-raw' +import rehypeSanitize from 'rehype-sanitize' import remarkGfm from 'remark-gfm'; import ChakraUIRenderer from 'chakra-ui-markdown-renderer'; import { Center, Link, Text, Flex } from '@chakra-ui/react'; @@ -41,6 +43,15 @@ const chakraUiRendererTheme: Parameters[0] = { ); }, + img: (props) => { + const { children, src } = props; + + return ( +
+ {children +
+ ); + }, }; @@ -59,7 +70,7 @@ const App: NextPage = ({ markdown }: SSProps) => ( - + diff --git a/yarn.lock b/yarn.lock index 7732e739..a91008d4 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3460,6 +3460,11 @@ resolved "https://registry.npmjs.org/@types/parse-json/-/parse-json-4.0.0.tgz" integrity sha512-//oorEZjL6sbPcKUaCdIGlIUeH26mgzimjBB77G6XRgnDl/L5wOnpyBGRe/Mmf5CVW3PwEBE1NjiMZ/ssFh4wA== +"@types/parse5@^6.0.0": + version "6.0.3" + resolved "https://registry.npmjs.org/@types/parse5/-/parse5-6.0.3.tgz#705bb349e789efa06f43f128cef51240753424cb" + integrity sha512-SuT16Q1K51EAVPz1K29DJ/sXjhSQ0zjvsypYJ6tlwVsRV9jwW5Adq2ch8Dq8kDBCkYnELS7N7VNCSB5nC56t/g== + "@types/prettier@^2.1.5": version "2.7.1" resolved "https://registry.npmjs.org/@types/prettier/-/prettier-2.7.1.tgz" @@ -6024,11 +6029,78 @@ has@^1.0.3: dependencies: function-bind "^1.1.1" +hast-util-from-parse5@^7.0.0: + version "7.1.2" + resolved "https://registry.npmjs.org/hast-util-from-parse5/-/hast-util-from-parse5-7.1.2.tgz#aecfef73e3ceafdfa4550716443e4eb7b02e22b0" + integrity sha512-Nz7FfPBuljzsN3tCQ4kCBKqdNhQE2l0Tn+X1ubgKBPRoiDIu1mL08Cfw4k7q71+Duyaw7DXDN+VTAp4Vh3oCOw== + dependencies: + "@types/hast" "^2.0.0" + "@types/unist" "^2.0.0" + hastscript "^7.0.0" + property-information "^6.0.0" + vfile "^5.0.0" + vfile-location "^4.0.0" + web-namespaces "^2.0.0" + +hast-util-parse-selector@^3.0.0: + version "3.1.1" + resolved "https://registry.npmjs.org/hast-util-parse-selector/-/hast-util-parse-selector-3.1.1.tgz#25ab00ae9e75cbc62cf7a901f68a247eade659e2" + integrity sha512-jdlwBjEexy1oGz0aJ2f4GKMaVKkA9jwjr4MjAAI22E5fM/TXVZHuS5OpONtdeIkRKqAaryQ2E9xNQxijoThSZA== + dependencies: + "@types/hast" "^2.0.0" + +hast-util-raw@^7.2.0: + version "7.2.3" + resolved "https://registry.npmjs.org/hast-util-raw/-/hast-util-raw-7.2.3.tgz#dcb5b22a22073436dbdc4aa09660a644f4991d99" + integrity sha512-RujVQfVsOrxzPOPSzZFiwofMArbQke6DJjnFfceiEbFh7S05CbPt0cYN+A5YeD3pso0JQk6O1aHBnx9+Pm2uqg== + dependencies: + "@types/hast" "^2.0.0" + "@types/parse5" "^6.0.0" + hast-util-from-parse5 "^7.0.0" + hast-util-to-parse5 "^7.0.0" + html-void-elements "^2.0.0" + parse5 "^6.0.0" + unist-util-position "^4.0.0" + unist-util-visit "^4.0.0" + vfile "^5.0.0" + web-namespaces "^2.0.0" + zwitch "^2.0.0" + +hast-util-sanitize@^4.0.0: + version "4.1.0" + resolved "https://registry.npmjs.org/hast-util-sanitize/-/hast-util-sanitize-4.1.0.tgz#d90f8521f5083547095c5c63a7e03150303e0286" + integrity sha512-Hd9tU0ltknMGRDv+d6Ro/4XKzBqQnP/EZrpiTbpFYfXv/uOhWeKc+2uajcbEvAEH98VZd7eII2PiXm13RihnLw== + dependencies: + "@types/hast" "^2.0.0" + +hast-util-to-parse5@^7.0.0: + version "7.1.0" + resolved "https://registry.npmjs.org/hast-util-to-parse5/-/hast-util-to-parse5-7.1.0.tgz#c49391bf8f151973e0c9adcd116b561e8daf29f3" + integrity sha512-YNRgAJkH2Jky5ySkIqFXTQiaqcAtJyVE+D5lkN6CdtOqrnkLfGYYrEcKuHOJZlp+MwjSwuD3fZuawI+sic/RBw== + dependencies: + "@types/hast" "^2.0.0" + comma-separated-tokens "^2.0.0" + property-information "^6.0.0" + space-separated-tokens "^2.0.0" + web-namespaces "^2.0.0" + zwitch "^2.0.0" + hast-util-whitespace@^2.0.0: version "2.0.0" resolved "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-2.0.0.tgz" integrity sha512-Pkw+xBHuV6xFeJprJe2BBEoDV+AvQySaz3pPDRUs5PNZEMQjpXJJueqrpcHIXxnWTcAGi/UOCgVShlkY6kLoqg== +hastscript@^7.0.0: + version "7.2.0" + resolved "https://registry.npmjs.org/hastscript/-/hastscript-7.2.0.tgz#0eafb7afb153d047077fa2a833dc9b7ec604d10b" + integrity sha512-TtYPq24IldU8iKoJQqvZOuhi5CyCQRAbvDOX0x1eW6rsHSxa/1i2CCiptNTotGHJ3VoHRGmqiv6/D3q113ikkw== + dependencies: + "@types/hast" "^2.0.0" + comma-separated-tokens "^2.0.0" + hast-util-parse-selector "^3.0.0" + property-information "^6.0.0" + space-separated-tokens "^2.0.0" + hey-listen@^1.0.8: version "1.0.8" resolved "https://registry.npmjs.org/hey-listen/-/hey-listen-1.0.8.tgz" @@ -6058,6 +6130,11 @@ html-escaper@^3.0.3: resolved "https://registry.npmjs.org/html-escaper/-/html-escaper-3.0.3.tgz" integrity sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ== +html-void-elements@^2.0.0: + version "2.0.1" + resolved "https://registry.npmjs.org/html-void-elements/-/html-void-elements-2.0.1.tgz#29459b8b05c200b6c5ee98743c41b979d577549f" + integrity sha512-0quDb7s97CfemeJAnW9wC0hw78MtW7NU3hqtCD75g2vFlDLt36llsYD7uB7SUzojLMP24N5IatXf7ylGXiGG9A== + htmlparser2@^8.0.1: version "8.0.1" resolved "https://registry.npmjs.org/htmlparser2/-/htmlparser2-8.0.1.tgz" @@ -8033,6 +8110,11 @@ parse5-htmlparser2-tree-adapter@^7.0.0: domhandler "^5.0.2" parse5 "^7.0.0" +parse5@^6.0.0: + version "6.0.1" + resolved "https://registry.npmjs.org/parse5/-/parse5-6.0.1.tgz#e1a1c085c569b3dc08321184f19a39cc27f7c30b" + integrity sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw== + parse5@^7.0.0, parse5@^7.1.1: version "7.1.1" resolved "https://registry.npmjs.org/parse5/-/parse5-7.1.1.tgz" @@ -8344,10 +8426,10 @@ react-is@^18.0.0, react-is@^18.2.0: resolved "https://registry.npmjs.org/react-is/-/react-is-18.2.0.tgz" integrity sha512-xWGDIW6x921xtzPkhiULtthJHoJvBbF3q26fzloPCK0hsvxtPVelvftw3zjbHWSkR2km9Z+4uxbDDK/6Zw9B8w== -react-markdown@^8.0.3: - version "8.0.3" - resolved "https://registry.npmjs.org/react-markdown/-/react-markdown-8.0.3.tgz" - integrity sha512-We36SfqaKoVNpN1QqsZwWSv/OZt5J15LNgTLWynwAN5b265hrQrsjMtlRNwUvS+YyR3yDM8HpTNc4pK9H/Gc0A== +react-markdown@8.0.7: + version "8.0.7" + resolved "https://registry.npmjs.org/react-markdown/-/react-markdown-8.0.7.tgz#c8dbd1b9ba5f1c5e7e5f2a44de465a3caafdf89b" + integrity sha512-bvWbzG4MtOU62XqBx3Xx+zB2raaFFsq4mYiAzfjXJMEz2sixgeAfraA3tvzULF02ZdOMUOKTBFFaZJDDrq+BJQ== dependencies: "@types/hast" "^2.0.0" "@types/prop-types" "^15.0.0" @@ -8360,7 +8442,7 @@ react-markdown@^8.0.3: remark-parse "^10.0.0" remark-rehype "^10.0.0" space-separated-tokens "^2.0.0" - style-to-object "^0.3.0" + style-to-object "^0.4.0" unified "^10.0.0" unist-util-visit "^4.0.0" vfile "^5.0.0" @@ -8487,6 +8569,24 @@ regjsparser@^0.9.1: dependencies: jsesc "~0.5.0" +rehype-raw@^6.1.1: + version "6.1.1" + resolved "https://registry.npmjs.org/rehype-raw/-/rehype-raw-6.1.1.tgz#81bbef3793bd7abacc6bf8335879d1b6c868c9d4" + integrity sha512-d6AKtisSRtDRX4aSPsJGTfnzrX2ZkHQLE5kiUuGOeEoLpbEulFF4hj0mLPbsa+7vmguDKOVVEQdHKDSwoaIDsQ== + dependencies: + "@types/hast" "^2.0.0" + hast-util-raw "^7.2.0" + unified "^10.0.0" + +rehype-sanitize@^5.0.1: + version "5.0.1" + resolved "https://registry.npmjs.org/rehype-sanitize/-/rehype-sanitize-5.0.1.tgz#dac01a7417bdd329260c74c74449697b4be5eb56" + integrity sha512-da/jIOjq8eYt/1r9GN6GwxIR3gde7OZ+WV8pheu1tL8K0D9KxM2AyMh+UEfke+FfdM3PvGHeYJU0Td5OWa7L5A== + dependencies: + "@types/hast" "^2.0.0" + hast-util-sanitize "^4.0.0" + unified "^10.0.0" + remark-gfm@^3.0.1: version "3.0.1" resolved "https://registry.npmjs.org/remark-gfm/-/remark-gfm-3.0.1.tgz" @@ -8919,10 +9019,10 @@ strip-json-comments@^3.1.0, strip-json-comments@^3.1.1: resolved "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz" integrity sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig== -style-to-object@^0.3.0: - version "0.3.0" - resolved "https://registry.npmjs.org/style-to-object/-/style-to-object-0.3.0.tgz" - integrity sha512-CzFnRRXhzWIdItT3OmF8SQfWyahHhjq3HwcMNCNLn+N7klOOqPjMeG/4JSu77D7ypZdGvSzvkrbyeTMizz2VrA== +style-to-object@^0.4.0: + version "0.4.1" + resolved "https://registry.npmjs.org/style-to-object/-/style-to-object-0.4.1.tgz#53cf856f7cf7f172d72939d9679556469ba5de37" + integrity sha512-HFpbb5gr2ypci7Qw+IOhnP2zOU7e77b+rzM+wTzXzfi1PrtBCX0E7Pk4wL4iTLnhzZ+JgEGAhX81ebTg/aYjQw== dependencies: inline-style-parser "0.1.1" @@ -9442,6 +9542,14 @@ vary@^1: resolved "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz" integrity sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg== +vfile-location@^4.0.0: + version "4.1.0" + resolved "https://registry.npmjs.org/vfile-location/-/vfile-location-4.1.0.tgz#69df82fb9ef0a38d0d02b90dd84620e120050dd0" + integrity sha512-YF23YMyASIIJXpktBa4vIGLJ5Gs88UB/XePgqPmTa7cDA+JeO3yclbpheQYCHjVHBn/yePzrXuygIL+xbvRYHw== + dependencies: + "@types/unist" "^2.0.0" + vfile "^5.0.0" + vfile-message@^3.0.0: version "3.1.2" resolved "https://registry.npmjs.org/vfile-message/-/vfile-message-3.1.2.tgz" @@ -9474,6 +9582,11 @@ walker@^1.0.8: dependencies: makeerror "1.0.12" +web-namespaces@^2.0.0: + version "2.0.1" + resolved "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz#1010ff7c650eccb2592cebeeaf9a1b253fd40692" + integrity sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ== + web-vitals@^3.1.1: version "3.1.1" resolved "https://registry.yarnpkg.com/web-vitals/-/web-vitals-3.1.1.tgz#bb124a03df7a135617f495c5bb7dbc30ecf2cce3"