Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat(docs): 📝 Adding image/video support in documentation #359

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat(docs): 📝 Adding image/video support in documentation #359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
34 changes: 19 additions & 15 deletions User Guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Starmap User Guide

<a href="https://www.loom.com/share/ff446968fa684ed4b83e98c22ec306d3" target="_blank"><img align="center" src="https://cdn.loom.com/sessions/thumbnails/ff446968fa684ed4b83e98c22ec306d3-with-play.gif"></a>

<img align="center" src="https://cdn.loom.com/sessions/thumbnails/ff446968fa684ed4b83e98c22ec306d3-with-play.gif">

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.
Expand All @@ -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).

Expand All @@ -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
Expand Down Expand Up @@ -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:

```
Expand Down Expand Up @@ -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 <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.

```
```[tasklist]
Expand All @@ -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 <https://github.com/pln-planning-tools/Starmap/issues/245> for more details.

```
Children:
Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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 <https://github.com/pln-planning-tools/Starmap/issues/245> for more details

```
Title: [Team/Project Name] [Duration] Roadmap
Expand All @@ -204,6 +207,7 @@ Starmap Link: [Starmap Link]
```

#### Child Milestone Issues

```
Title: [Team/Project Name] [Milestone Title]

Expand Down
4 changes: 3 additions & 1 deletion next.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
4 changes: 3 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
13 changes: 12 additions & 1 deletion pages/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -41,6 +43,15 @@ const chakraUiRendererTheme: Parameters<typeof ChakraUIRenderer>[0] = {
</Link>
);
},
img: (props) => {
const { children, src } = props;

return (
<Center>
<Image src={src as string} alt={children as string} width={500} height={500} />
</Center>
);
},
};


Expand All @@ -59,7 +70,7 @@ const App: NextPage<SSProps> = ({ markdown }: SSProps) => (
</Link>
</NextLink>
</Flex>
<ReactMarkdown components={ChakraUIRenderer(chakraUiRendererTheme)} children={markdown} remarkPlugins={[remarkGfm]} />
<ReactMarkdown components={ChakraUIRenderer(chakraUiRendererTheme)} children={markdown} remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeRaw, rehypeSanitize]} />
</article>
</Center>
</>
Expand Down
131 changes: 122 additions & 9 deletions yarn.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand All @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"

Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down