metamask / metamask-docs-next

the docs: next generation

Built With:

• React
• Gatsby
• ❤️ from ConsenSys Digital Experiences Circle

🚀 Quick start

Ask @davidnguyen88 or @jlazoff for config files

1. Start it up

   git clone [email protected]:MetaMask/website.git
   yarn
   yarn develop

2. View site

   MetaMask is now running at http://localhost:8000!

   There is also a GraphQL API at http://localhost:8000/___graphql. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the Gatsby tutorial.

What's where?

Gatsby file structure documentation

.
├── public/
├── src/
    ├── components/
    ├── fonts/
    ├── fragments/
      ├──GraphQL_Documentation.md
    ├── images/
      ├── icons/
      ├── social-icons/
      ├── metamask-logo.svg
      ├── ...
    ├── lib/
      ├── theme.js
    ├── pages/
      ├── index.js
      ├── about.js
      ├── ...
    ├── html.js
├── gatsby-config.js
├── gatsby.[development].env]
├── GraphQL_Query_Documentation.md
├── package.json
└── README.md

Key Files

gatsby-config.js

The main configuration file for a Gatsby site. This is where you can specify information about your site (metadata), site title ,and description, which Gatsby plugins we are using, etc. (Check out the config docs for more detail).

src/fragments/ GraphQL query fragments that create standard data requests across components

src/lib/theme.js Contains styling constants for font sizes and weights, device sizes for media queries, shadows, and colors.

public/

Automatically generated output of gatsby build process for production.

src/pages

Files within this directory are turned into routes with the name of the file (e.g. about.js becomes /about). Only files within /pages are allowed to make dynamic GraphQL queries which cascade data down to components.

src/html.js Entry file used by Gatsby for all rendered pages html template

metamask-docs-next's Issues

fix index route for `/guide/`

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

Features for version 1

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

Error when using top level await

Get parity with metamask-docs

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

remove tsfmt

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

deep link to heading

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