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