feat: add docs

.changeset/config.json

@@ -2,7 +2,7 @@
   "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
   "changelog": "@changesets/cli/changelog",
   "commit": false,
-  "linked": [["@stacks/ui", "@stacks/ui-*"]],
+  "linked": [],
   "access": "public",
   "baseBranch": "master",
   "updateInternalDependencies": "patch",

.gitignore

@@ -2,7 +2,7 @@ dist
 node_modules
 .idea
 .vscode
-lib
+./lib
 mdincludes
 emotion
 yarn-error.log

docs/.eslintrc.js

@@ -0,0 +1,29 @@
+module.exports = {
+  extends: ['@blockstack/eslint-config'],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    createDefaultProgram: true,
+    project: './tsconfig.json',
+  },
+  env: {
+    browser: true,
+    node: true,
+    es6: true,
+  },
+  globals: {
+    page: true,
+    browser: true,
+    context: true,
+    jestPuppeteer: true,
+  },
+  rules: {
+    '@typescript-eslint/no-unsafe-assignment': 0,
+    '@typescript-eslint/no-unsafe-member-access': 0,
+    '@typescript-eslint/no-unsafe-call': 0,
+    '@typescript-eslint/no-unsafe-return': 0,
+    '@typescript-eslint/explicit-module-boundary-types': 0,
+    '@typescript-eslint/ban-ts-comment': 0,
+    '@typescript-eslint/ban-ts-ignore': 0,
+    '@typescript-eslint/restrict-template-expressions': 0,
+  },
+};

docs/.github/workflows/main.yml

@@ -0,0 +1,19 @@
+name: Code quality
+on: [push]
+
+jobs:
+  code_quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set Node Version
+        uses: actions/[email protected]
+        with:
+          node-version: 14
+      - name: Install deps
+        run: yarn --frozen-lockfile
+      - name: Lint
+        run: yarn lint
+      - name: Typecheck
+        run: yarn typecheck

docs/.gitignore

@@ -0,0 +1,45 @@
+# OS or Editor folders
+.DS_Store
+node_modules
+
+# Jekyllg
+_site
+.sass-cache
+.jekyll-metadata
+Gemfile.lock
+**/.DS_Store
+**/desktop.ini
+**/.svn
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+.vercel
+/.next/
+/out/
+/build/
+
+# production
+/build
+
+# misc
+.env*
+.idea
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.now
+.mdx-data
+.cache
+.yalc
+yalc.lock
+.cache

docs/.prettierrc

@@ -0,0 +1 @@
+module.exports = require('@blockstack/prettier-config');

docs/.vercelignore

@@ -0,0 +1,11 @@
+.github
+.next
+.vercel
+.mdx-data
+.idea
+node_modules
+build
+README.md
+.cache
+.yalc
+yalc.lock

docs/README.md

@@ -0,0 +1,30 @@
+# Blockstack documentation
+
+![A screenshot of docs.blockstack.org](/public/images/docs-homepage.png)
+
+## Running and building the site locally
+
+If you are interested in contributing to the site and making changes, please refer to our [contributing guide here](https://docs.blockstack.org/ecosystem/contributing).
+
+## Generated documentation
+
+### Blockstack CLI reference
+
+The `src/_data/cli-reference.json` file is generated from the `blockstack-cli` subcommand `docs`.
+
+1. Install the latest version of the cli according to the instructions at: https://github.com/blockstack/cli-blockstack
+
+2. Generate the json for the cli in the `docs.blockstack` repo.
+
+   ```
+   $ blockstack-cli docs > src/_data/cli-reference.json
+   ```
+
+### Clarity Reference
+
+There is a json file that is generated via the `stacks-blockchain` repo, which automatically brings it over to this repo
+via a github action.
+
+### FAQs
+
+All of the FAQs found at `/reference/faqs` are pulled dynamically from the zendesk api and rendered in this project.

docs/babel.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  presets: ['next/babel', '@emotion/babel-preset-css-prop'],
+  plugins: ['./lib/babel-plugin-nextjs-mdx-patch', 'babel-plugin-macros', '@emotion'],
+};

docs/lib/babel-plugin-nextjs-mdx-patch.js

@@ -0,0 +1,30 @@
+/**
+ * Currently it's not possible to export data fetching functions from MDX pages
+ * because MDX includes them in `layoutProps`, and Next.js removes them at some
+ * point, causing a `ReferenceError`.
+ *
+ * https://github.com/mdx-js/mdx/issues/742#issuecomment-612652071
+ *
+ * This plugin can be removed once MDX removes `layoutProps`, at least that
+ * seems to be the current plan.
+ */
+
+// https://nextjs.org/docs/basic-features/data-fetching
+const DATA_FETCH_FNS = ['getStaticPaths', 'getStaticProps', 'getServerProps'];
+
+module.exports = () => {
+  return {
+    visitor: {
+      ObjectProperty(path) {
+        if (
+          DATA_FETCH_FNS.includes(path.node.value.name) &&
+          path.findParent(
+            path => path.isVariableDeclarator() && path.node.id.name === 'layoutProps'
+          )
+        ) {
+          path.remove();
+        }
+      },
+    },
+  };
+};

docs/lib/mdx-frontmatter-loader.js

@@ -0,0 +1,50 @@
+const fm = require('gray-matter');
+const remark = require('remark');
+const strip = require('strip-markdown');
+
+const getHeadings = mdxContent => {
+  const regex = /\n(#+)(.*)/gm;
+  const found = mdxContent.match(regex);
+  const getLevel = string => string.split('#');
+  const headings =
+    found && found.length
+      ? found.map(f => {
+          const md = f.split('# ')[1];
+          let content = md;
+          remark()
+            .use(strip)
+            .process(md, (err, file) => {
+              if (err) throw err;
+              content = file.contents.toString().trim();
+            });
+          const level = getLevel(f).length;
+          return { content, level };
+        })
+      : [];
+  return headings;
+};
+
+// @see https://github.com/expo/expo/blob/master/docs/common/md-loader.js
+async function mdxFrontmatterLoader(src) {
+  const callback = this.async();
+  const { content, data } = fm(src);
+  const headings = getHeadings(content);
+  const code =
+    `import { MDWrapper } from '@components/mdx/markdown-wrapper';
+export default function Layout({ children, ...props }){
+  return (
+    <MDWrapper frontmatter={${JSON.stringify({
+      ...data,
+      headings,
+    })}} {...props}>
+      {children}
+    </MDWrapper>
+)
+}
+
+` + content;
+
+  return callback(null, code);
+}
+
+module.exports = mdxFrontmatterLoader;

docs/lib/rehype-image-size.js

@@ -0,0 +1,36 @@
+const memoize = require('micro-memoize');
+const visit = require('unist-util-visit');
+const pAll = require('p-all');
+const sizeOf = require('image-size');
+
+/**
+ * Simple plugin to get the size of local images so we can use it in react
+ */
+const rehypeImageSize = () => {
+  async function transformer(tree) {
+    const nodes = [];
+    visit(tree, 'element', node => {
+      if (node.tagName !== 'img') {
+        return;
+      } else {
+        nodes.push(node);
+      }
+    });
+    await pAll(
+      nodes.map(node => () => visitor(node)),
+      { concurrency: 25 }
+    );
+    return tree;
+  }
+  async function visitor(node) {
+    const isRelative =
+      node && node.properties && node.properties.src && node.properties.src.startsWith('/');
+    if (isRelative) {
+      const dimensions = sizeOf(`public/${node.properties.src}`);
+      node.properties['dimensions'] = dimensions;
+    }
+  }
+  return transformer;
+};
+
+module.exports = memoize(rehypeImageSize);

docs/lib/rehype-plugins.js

@@ -0,0 +1,7 @@
+const memoize = require('micro-memoize');
+const { rehypeVscode } = require('unified-vscode');
+const rehypeImgs = require('./rehype-image-size');
+
+const rehypePlugins = [memoize(rehypeVscode), rehypeImgs];
+
+module.exports = { rehypePlugins };