mirror of https://github.com/lukechilds/docs.git
Thomas Osmonson
5 years ago
12 changed files with 441 additions and 136 deletions
@ -0,0 +1,31 @@ |
|||||
|
import React from 'react'; |
||||
|
import { mdx, MDXProvider } from '@mdx-js/react'; |
||||
|
|
||||
|
export const hydrate = ({ source, renderedOutput, scope = {} }, components) => { |
||||
|
// first we set up the scope which has to include the mdx custom
|
||||
|
// create element function as well as any components we're using
|
||||
|
const fullScope = { mdx, ...components, ...scope }; |
||||
|
const keys = Object.keys(fullScope); |
||||
|
const values = Object.values(fullScope); |
||||
|
|
||||
|
// now we eval the source code using a function constructor
|
||||
|
// in order for this to work we need to have React, the mdx createElement,
|
||||
|
// and all our components in scope for the function, which is the case here
|
||||
|
// we pass the names (via keys) in as the function's args, and execute the
|
||||
|
// function with the actual values.
|
||||
|
const hydratedFn = new Function( |
||||
|
'React', |
||||
|
...keys, |
||||
|
`${source} |
||||
|
return React.createElement(MDXContent, {});` |
||||
|
)(React, ...values); |
||||
|
|
||||
|
// wrapping the content with MDXProvider will allow us to customize the standard
|
||||
|
// markdown components (such as "h1" or "a") with the "components" object
|
||||
|
// @ts-ignore
|
||||
|
const wrappedWithMdxProvider = React.createElement(MDXProvider, { components }, hydratedFn); |
||||
|
|
||||
|
// finally, set the the output as the new result so that react will re-render for us
|
||||
|
// and cancel the idle callback since we don't need it anymore
|
||||
|
return wrappedWithMdxProvider; |
||||
|
}; |
||||
@ -0,0 +1,114 @@ |
|||||
|
[ |
||||
|
{ |
||||
|
"title": "Authentication", |
||||
|
"routes": [ |
||||
|
{ "path": "browser/todo-list" }, |
||||
|
{ "path": "develop/connect/overview" }, |
||||
|
{ "path": "develop/profiles" } |
||||
|
] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "Data Storage", |
||||
|
"routes": [ |
||||
|
{ "path": "storage/overview" }, |
||||
|
{ "path": "develop/storage" }, |
||||
|
{ "path": "storage/authentication" }, |
||||
|
{ "path": "storage/write-to-read" } |
||||
|
] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "Data Indexing", |
||||
|
"routes": [ |
||||
|
{ "path": "develop/radiks-intro" }, |
||||
|
{ "path": "develop/radiks-setup" }, |
||||
|
{ "path": "develop/radiks-models" }, |
||||
|
{ "path": "develop/radiks-collaborate" }, |
||||
|
{ "path": "develop/radiks-server-extras" } |
||||
|
] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "Smart Contracts", |
||||
|
"routes": [ |
||||
|
{ "path": "core/smart/overview" }, |
||||
|
{ "path": "core/smart/tutorial" }, |
||||
|
{ "path": "core/smart/tutorial-counter" }, |
||||
|
{ "path": "core/smart/tutorial-test" }, |
||||
|
{ "path": "develop/connect/use-with-clarity" }, |
||||
|
{ "path": "core/smart/principals" }, |
||||
|
{ "path": "core/smart/testnet-node" }, |
||||
|
{ "path": "core/smart/cli-wallet-quickstart" } |
||||
|
] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "Naming Services", |
||||
|
"routes": [ |
||||
|
{ "path": "core/naming/introduction" }, |
||||
|
{ "path": "core/naming/architecture" }, |
||||
|
{ "path": "core/naming/namespaces" }, |
||||
|
{ "path": "core/naming/comparison" }, |
||||
|
{ "path": "core/naming/tutorial_subdomains" }, |
||||
|
{ "path": "core/naming/search" }, |
||||
|
{ "path": "core/faq_technical" }, |
||||
|
{ "path": "core/naming/pickname" }, |
||||
|
{ "path": "core/naming/creationhowto" }, |
||||
|
{ "path": "core/naming/resolving" }, |
||||
|
{ "path": "core/naming/register" }, |
||||
|
{ "path": "core/naming/manage" }, |
||||
|
{ "path": "core/naming/subdomains" }, |
||||
|
{ "path": "core/naming/forks" } |
||||
|
] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "Data Portability (Preview)", |
||||
|
"routes": [{ "path": "develop/collections" }, { "path": "develop/collection-type" }] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "Host a Storage Hub", |
||||
|
"routes": [ |
||||
|
{ "path": "storage/hub-operation" }, |
||||
|
{ "path": "storage/amazon-s3-deploy" }, |
||||
|
{ "path": "storage/digital-ocean-deploy" }, |
||||
|
{ "path": "storage/hello-hub-choice" }, |
||||
|
{ "path": "storage/gaia-admin" } |
||||
|
] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "Atlas", |
||||
|
"routes": [ |
||||
|
{ "path": "core/atlas/overview" }, |
||||
|
{ "path": "core/atlas/howitworks" }, |
||||
|
{ "path": "core/atlas/howtouse" } |
||||
|
] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "Blockstack and Stacks Tokens", |
||||
|
"routes": [ |
||||
|
{ "path": "org/overview" }, |
||||
|
{ "path": "faqs/allFAQS" }, |
||||
|
{ "path": "org/token" }, |
||||
|
{ "path": "org/whitepaper-blockchain" }, |
||||
|
{ "path": "org/wallet-intro" }, |
||||
|
{ "path": "org/wallet-install" }, |
||||
|
{ "path": "org/wallet-use" }, |
||||
|
{ "path": "org/wallet-troubleshoot" }, |
||||
|
{ "path": "org/tokenholders" } |
||||
|
] |
||||
|
}, |
||||
|
{ |
||||
|
"title": "References", |
||||
|
"routes": [ |
||||
|
{ "path": "core/cmdLineRef" }, |
||||
|
{ "path": "core/smart/clarityRef" }, |
||||
|
{ "path": "core/smart/rpc-api" }, |
||||
|
{ "path": "common/javascript_ref" }, |
||||
|
{ "path": "common/android_ref" }, |
||||
|
{ "path": "common/ios_ref" }, |
||||
|
{ "path": "common/core_ref" }, |
||||
|
{ "path": "core/wire-format" }, |
||||
|
{ "path": "storage/config-schema" }, |
||||
|
{ "path": "org/secureref" }, |
||||
|
{ "path": "develop/overview_auth" }, |
||||
|
{ "path": "org/terms" } |
||||
|
] |
||||
|
} |
||||
|
] |
||||
@ -0,0 +1,253 @@ |
|||||
|
--- |
||||
|
title: How to contribute |
||||
|
description: Learn how this site is built, and how you could contribute to it. |
||||
|
--- |
||||
|
|
||||
|
# How to contribute |
||||
|
|
||||
|
Welcome! Thank you for your interest in contributing and helping make these docs as good as they can be! This page will |
||||
|
outline how this site is built, its general structure, getting it running locally, and some helpful tips for using all of its features. |
||||
|
|
||||
|
## Next.js, MDX, Markdown |
||||
|
|
||||
|
This docs site is built with [Next.js](https://github.com/vercel/next.js) and uses something called [MDX](https://mdxjs.com/). |
||||
|
Next.js is a framework built on top of React, and MDX is a tool that enables writing React code (JSX) within standard |
||||
|
Markdown files. In addition to being able to write JSX in Markdown, it allows the application to render out all of the |
||||
|
Markdown content with React components! This means that we are able to do some pretty complex things while a |
||||
|
contributor only has to know how to write Markdown. |
||||
|
|
||||
|
-> Don't know what Markdown is? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/) for getting started with Markdown. |
||||
|
|
||||
|
## Getting started |
||||
|
|
||||
|
To get started working locally with the site, a few things are needed: |
||||
|
|
||||
|
- Familiarity with `git`, GitHub, and the command line. [Read more here.](https://docs.github.com/en/github/getting-started-with-github/quickstart) |
||||
|
- [`node` + `npm`,](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) and [`yarn` installed](https://yarnpkg.com/getting-started/install) on your machine. |
||||
|
- Some kind of code editor, such as VSCode, Sublime, or WebStorm. |
||||
|
|
||||
|
### Working with GitHub |
||||
|
|
||||
|
All of the code for this site is open source, located at the [GitHub repository here](https://github.com/blockstack/docs.blockstack). |
||||
|
Before you start editing anything, you will need to fork the repo so that you can have your own copy of the code under |
||||
|
your GitHub profile. On the [repository's page](https://github.com/blockstack/docs.blockstack), you should be able to |
||||
|
see a button in the upper right of the screen that says "Fork". [You can read about Forking here.](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) |
||||
|
|
||||
|
This is a generalized workflow for contributing to these docs: |
||||
|
|
||||
|
- Clone your fork to your local machine with this command `git clone git@github.com:<YOUR_USERNAME>/docs.blockstack.git` |
||||
|
- Create a branch `git checkout -b feat/my-feature-branch`. |
||||
|
- Run the command `yarn` to install all of the dependencies. |
||||
|
- Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. |
||||
|
- Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. |
||||
|
- Visit GitHub and make your pull request. |
||||
|
|
||||
|
### Running the site locally |
||||
|
|
||||
|
Once you have the project on your computer and the dependencies have been installed via the `yarn` command, you can run |
||||
|
`yarn dev` and it should give you a message such as: |
||||
|
|
||||
|
```bash |
||||
|
➜ docs.blockstack git:(feat/my-helpful-contribution) ✗ yarn dev |
||||
|
yarn run v1.22.4 |
||||
|
$ yarn clean:build-files && next dev |
||||
|
$ rimraf .next |
||||
|
ready - started server on http://localhost:3000 |
||||
|
warn - You have enabled experimental feature(s). |
||||
|
warn - Experimental features are not covered by semver, and may cause unexpected or broken application behavior. Use them at your own risk. |
||||
|
|
||||
|
info - Using external babel configuration from /Users/YOUR_USERNAME/oss/docs.blockstack/babel.config.js |
||||
|
event - compiled successfully |
||||
|
``` |
||||
|
|
||||
|
The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). |
||||
|
|
||||
|
## Project structure |
||||
|
|
||||
|
### Pages |
||||
|
|
||||
|
If you are interested in only adding new documentation content to the site, the files that will be important to you are |
||||
|
located within `docs.blockstack/src/pages/*`: |
||||
|
|
||||
|
```bash showLineNumbers highlight=11 |
||||
|
docs.blockstack/ |
||||
|
.github/ |
||||
|
lib/ |
||||
|
node_modules/ |
||||
|
public/ |
||||
|
src/ |
||||
|
_data/ |
||||
|
_includes/ |
||||
|
common/ |
||||
|
components/ |
||||
|
pages/ |
||||
|
types/ |
||||
|
``` |
||||
|
|
||||
|
The routing for this site is file based, meaning if you created a folder within `/pages` named `clarity` and a then file |
||||
|
named `overview.md`, you would be able to navigate to `http://localhost:3000/clarity/overview` and you would see whatever |
||||
|
content is in that markdown file. |
||||
|
|
||||
|
### Frontmatter |
||||
|
|
||||
|
Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: |
||||
|
|
||||
|
```yaml |
||||
|
--- |
||||
|
title: This is my page title |
||||
|
description: A short, concise sentence describing what is on this page |
||||
|
--- |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. |
||||
|
When adding any new page, please include a `title` and `description`. |
||||
|
|
||||
|
-> **Did you know?** The term _Frontmatter_ comes from the section in a book at the beginning the details things like: Publisher’s name and address, Copyright information, Table of Contents, etc. |
||||
|
|
||||
|
### Dynamic sidebar |
||||
|
|
||||
|
The sidebar navigation is generated in a partially dynamic way. The application searches through a list of paths and |
||||
|
parses the markdown to get some information about the page, such as the title and headings contained within the page. |
||||
|
|
||||
|
#### Adding a new route |
||||
|
|
||||
|
If you are adding a new route, you have to add your route to a section contained within this file: `src/common/routes/all-routes.json` |
||||
|
|
||||
|
```bash showLineNumbers highlight=11 |
||||
|
docs.blockstack/ |
||||
|
.github/ |
||||
|
lib/ |
||||
|
node_modules/ |
||||
|
public/ |
||||
|
src/ |
||||
|
_data/ |
||||
|
_includes/ |
||||
|
common/ |
||||
|
routes/ |
||||
|
all-routes.json |
||||
|
get-routes.js |
||||
|
index.ts |
||||
|
components/ |
||||
|
pages/ |
||||
|
types/ |
||||
|
``` |
||||
|
|
||||
|
Here is an example of adding a new route (see line #8): |
||||
|
|
||||
|
```json highlight=8 |
||||
|
{ |
||||
|
"title": "Data Storage", |
||||
|
"routes": [ |
||||
|
{ "path": "storage/overview" }, |
||||
|
{ "path": "develop/storage" }, |
||||
|
{ "path": "storage/authentication" }, |
||||
|
{ "path": "storage/write-to-read" }, |
||||
|
{ "path": "clarity/my-new-page" } |
||||
|
] |
||||
|
}, |
||||
|
``` |
||||
|
|
||||
|
The script will process that file and pull out the title from the frontmatter of the document. |
||||
|
|
||||
|
### Non-standard pages |
||||
|
|
||||
|
There are a few pages within these docs that are non-standard markdown pages. This means they are using some kind of external data as their source, |
||||
|
such as the [Clarity Reference page](core/smart/clarityRef), or the [Blockstack CLI page](/core/cmdLineRef). These pages are using a function of Next.js called |
||||
|
[`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) which allows us to |
||||
|
fetch external data at runtime and use it in some way within our pages. |
||||
|
|
||||
|
## Tips and tricks |
||||
|
|
||||
|
### Always use Markdown when possible |
||||
|
|
||||
|
It's possible to write standard HTML when writing in Markdown, but that should be avoided at all costs. We use `remark` to |
||||
|
processes all Markdown, giving us things like automatically opening all external links in new windows, and adding IDs to headers. |
||||
|
When we write things in HTML, such as a link or image, we don't get the benefit of the remark plugins as consistently as we would |
||||
|
if we stuck to standar Markdown. |
||||
|
|
||||
|
### Code blocks |
||||
|
|
||||
|
The site uses `react-prism-renderer` and `prismjs` to add syntax highlighting to all of our code. You can see a full |
||||
|
list of [languages supported here](https://github.com/PrismJS/prism/tree/master/components). We have a custom language |
||||
|
definition for `clarity`, our smart contracting language located here. To add a new language, see this file: [`components/codeblock/index.tsx`](#). |
||||
|
|
||||
|
To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. |
||||
|
|
||||
|
```clarity |
||||
|
(define-data-var counter int 0) |
||||
|
|
||||
|
(define-public (get-counter) |
||||
|
(ok (var-get counter))) |
||||
|
``` |
||||
|
|
||||
|
#### Line highlighting |
||||
|
|
||||
|
You can pass some extra data to tell the component to highlight specific lines: |
||||
|
|
||||
|
` ```clarity highlight=1,4-6,13-17,28-32 ` |
||||
|
|
||||
|
Which will render: |
||||
|
|
||||
|
```clarity highlight=1,4-6,13-17,28-32 |
||||
|
(define-constant sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) |
||||
|
(define-constant recipient 'SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G) |
||||
|
|
||||
|
(define-fungible-token novel-token-19) |
||||
|
(begin (ft-mint? novel-token-19 u12 sender)) |
||||
|
(begin (ft-transfer? novel-token-19 u2 sender recipient)) |
||||
|
|
||||
|
(define-non-fungible-token hello-nft uint) |
||||
|
(begin (nft-mint? hello-nft u1 sender)) |
||||
|
(begin (nft-mint? hello-nft u2 sender)) |
||||
|
(begin (nft-transfer? hello-nft u1 sender recipient)) |
||||
|
|
||||
|
(define-public (test-emit-event) |
||||
|
(begin |
||||
|
(print "Event! Hello world") |
||||
|
(ok u1))) |
||||
|
(begin (test-emit-event)) |
||||
|
|
||||
|
(define-public (test-event-types) |
||||
|
(begin |
||||
|
(unwrap-panic (ft-mint? novel-token-19 u3 recipient)) |
||||
|
(unwrap-panic (nft-mint? hello-nft u2 recipient)) |
||||
|
(unwrap-panic (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) |
||||
|
(unwrap-panic (stx-burn? u20 tx-sender)) |
||||
|
(ok u1))) |
||||
|
|
||||
|
(define-map store ((key (buff 32))) ((value (buff 32)))) |
||||
|
(define-public (get-value (key (buff 32))) |
||||
|
(begin |
||||
|
(match (map-get? store ((key key))) |
||||
|
entry (ok (get value entry)) |
||||
|
(err 0)))) |
||||
|
(define-public (set-value (key (buff 32)) (value (buff 32))) |
||||
|
(begin |
||||
|
(map-set store ((key key)) ((value value))) |
||||
|
(ok u1))) |
||||
|
``` |
||||
|
|
||||
|
### Alerts |
||||
|
|
||||
|
We use another remark plugin to generate certain kinds of alerts inline in our documentation. |
||||
|
|
||||
|
```md |
||||
|
=> This will be a success style alert. |
||||
|
|
||||
|
-> This will be a standard note style alert. |
||||
|
|
||||
|
~> This will be a warning style alert. |
||||
|
|
||||
|
!> This will be a danger style alert. |
||||
|
``` |
||||
|
|
||||
|
Which renders: |
||||
|
|
||||
|
=> This will be a success style alert. |
||||
|
|
||||
|
-> This will be a standard note style alert. |
||||
|
|
||||
|
~> This will be a warning style alert. |
||||
|
|
||||
|
!> This will be a danger style alert. |
||||
Loading…
Reference in new issue