metamask / metamask-docs-next Goto Github PK

markup

• tips & warnings & errors
  
  
  

• include image in markdown (easily works in dev & prod)
  
  

• footnote

• external links vs. internal links
  

• EIP links with popover summary / description

• labels for deprecated / optional methods

• code examples

  • inline code that is non-runnable (single backticks)
  • autorun
  • no run
  • with UI / buttons
  • console logs & errors
  • html tab for copying example html
  • copy button
  • javascript / typescript support with a language indicator (display what language im looking at)
  • html on its own (no js with it, not runnable)
  • multi-step runnable code blocks with documentation in between each step (nice to have)
  • shell syntax highlighting
  • JSON syntax highlighting
  • regular text
  • code diffs

routing / nav

url structure:
https://${product package.json#homepage}/${group}/${type}/${section}/${content}#{heading}

where:

product = metamask | infura | any other product that might use this setup
type = guide | reference

groups is based on product
groups when product is metamask = mobile | extension | snaps | contributing
groups when product is infura = xyz | abc

groups MUST have guide
groups MAY have reference

when
type==guide - content is markdown
type==reference - content is generated from openrpc | openapi | typedoc

• leaving off components of the url has the effect of returning the 'first' section/content/heading
• the default for type is guide

examples of defaulting:

https://docs.metamask.io/mobile
https://docs.metamask.io/mobile/guide/introduction
https://docs.metamask.io/mobile/guide/introduction/introduction

https://docs.metamask.io/extension
https://docs.metamask.io/extension/best-practices/registering-function-names
https://docs.metamask.io/mobile/introduction#why-metamask

• when theres no group, goes to a docs homepage that lists out the groups and their fancy icons
  
• adding a new group
  • order of group in groups is easy to specify
  • name/title of the group is not derived by the filename (we dont want to be contrained by the file naming convention when it comes to chosing the title of a group)
  • every group has an introduction section.
  • every group has an icon
• adding new content when type is guide
  • order of content in group is determined by the frontmatter
  • title of content from frontmatter
  • url fragment of content from frontmatter
• each group+type should show sidenav with all the sections/content/headings
  • collapse contents' headings when not currently on the content page
• header nav with link between different types (switch from guide to reference)
• header nav with links between groups

other

• contributors list (ideally auto pulled from github, but to replace this)
• pages with markdown have an 'edit this page on gh' link
• cache busting on new release
• notify users if new release avail (give a refresh button in that case)
• good search is key (ideally using something like algolia)

metrics

• rate page on scale of 1-n on 'was this page helpful'
  
• integrate with what ever metrics tools we are using for other sites
• visibility on vercel's analytics

build tools

• markdown linting
  • link validity checking (ensure links return non 4-5xx)
• code examples checked against eslint config (typescript and javascript)
• markdown is built with generateStaticParams (use as much statically built things as possible)
• deploys to vercel
• PR previews / general vercel <-> github integration

As a user i'd like to deep link to a markdown heading on a specific page

Right now /guide doesnt go anywhere, but it should go to the isIndex route we defined in front matter

We should get parity with metamask-docs

that means:

• Same markdown used (or very close, maybe massaged)
• MetaMask-like design
• Shipped as a static site

we have a tsfmt.json file in the repo, but we use prettier, so we should just be using that with proper editor extensions