This README explains the user cases, source file organization, and procedures for building the Blockstack documentation. You can find the documentation at https://docs.blockstack.com
## Use Cases
Blockstack is a ecosystem build around a platform. There are several types of users to support with the documentation. Types are exist when they can operate within a vertical of the ecosystem. These are the users that can appear within this ecosystem and that the docs must support.
<table>
<tr>
<th>Users</th>
<th>Description</th>
</tr>
<tr>
<th>STX holders</th>
<td>Users who have purchased STX and who use our wallet to move STX holdings. These users want to know about Blockstack as a company and STX as an investment token. They have a Blockstack identity, they use the Blockstack wallet, and may also use the Blockstack explorer.</td>
</tr>
<tr>
<th>DApp users</th>
<td>Users who make use of applications built on the Blockstack platform. These users have a Blockstack identity and typically use the Blockstack Browser at some point.</td>
</tr>
<tr>
<th>Dapp developers or DApp miners</th>
<td>Users who develop applications on the Blockstack platform. These users may be application miners but are not always. Special content exists for developers that are also miners.</td>
</tr>
<tr>
<th>Hub Providers</th>
<td>Users who sell or maintain a Gai services are hub providers. They may also be application miners but need not be. These users may be more devops user types as opposed to developers.</td>
</tr>
<tr>
<th>Core service programmers</th>
<td>These are users that provide Blockstack CORE servers or who write Clarity contracts. These are also users who build wallets or explorers into the Blockstack platform.</td>
</tr>
</table>
Finally, a key user set but seldom mentioned for any company docs is the company employees. These users are expected to make use of the documentation when onboarding or to support other users.
## Documentation backend
Our documentation is written in Markdown (`.md`), built using [Jekyll](https://jekyllrb.com/), and deployed to a Netlify server. Serving the content from Netlify allows us to use functionality (plugins/javascript) not supported with standard GitHub pages.
Blockstack versions it source files in a public GitHub repo (duh :smile). You can submit changes by cloning, forking, and submitting a pull request. You can also make use of the **Edit this page on GitHub** link from any https://docs.blockstack.org page.
Some content is single sourced. Modifying single source content requires an understanding of that concept, how it works with Liquid tags, and the organization of this repo's source files.
[UIKit](https://getuikit.com/docs/introduction) provides the documentation theme. There is explicit use of HTML plus UIKit components directly in files where needed for special layouts. And there is use of CSV and JSON source files transformed with [Liquid template language](https://help.shopify.com/en/themes/liquid) to produce reference content.
## How the Source Files are Organized
Directories that contain information used to build content.
<table>
<tr>
<th>Directory</th>
<th>Purpose</th>
<th>Technical Repo(s)</th>
</tr>
<tr>
<td>_android</td>
<td>SDK tutorial. Part of the <ahref="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml">developer menu</a>.</td>
<td>Information for end-users about our identity, Storage, and using the browser. There are also three of the original tutorials in there. User docs controlled by in the the <ahref="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_usenew.yml">user menu</a>. The three tutorials that appear in the <ahref="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml">developer menu</a> There is an <ahref="https://github.com/blockstack/docs.blockstack/issues/501"target="_blank">outstanding issue</a> to move these.</td>
<td>Contains several shell files that redirect to our reference documentation sites such as Javascript, IOS, and so forth. The reference docs are linked from the developer, core, and Gaia menus.</td>
<td>Each of these references are generated by their respective repos, core.blockstack.org from <code>blockstack-core</code>, Javascript docs from the <code>blockstack.js</code> and so forth.</td>
</tr>
<tr>
<td>_core</td>
<td>Information for wallet, blockchain, or Clarity developers -- including Atlas, BNS, and so forth. <b>This content STILL needs to be synced with the master docs subdirectory in <ahref="https://github.com/blockstack/blockstack-core/tree/master/docs"target="_blank">blockstack-core</a>.</b></td>
<td>Information for application miners covers using the Javascript library, our mobile SDKs, and the concepts hat support them. Navigation controlled by <ahref="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml">developer menu</a></td>
<td>This information was never associated with a single repo. Much of it does rely heavily on <ahref="https://github.com/blockstack/blockstack.js">https://github.com/blockstack/blockstack.js</a>.</td>
</tr>
<tr>
<td>_faqs</td>
<td>Contains files for single-sourcing all the FAQs. The Blockstack docs has a single page that <ahref="https://docs.blockstack.org/faqs/allfaqs"target="_blank">lists all the faqs</a>; then several pages in different sections re-use this information. See the FAQs section below for detail about how these files figure into FAQS.</td>
<td>Not related to repo.</td>
</tr>
<tr>
<td>_includes</td>
<td>Information reused (markdown or html) in many places, common html used in pages and notes. </td>
<td>These files don't correspond to a repository.</td>
</tr>
<tr>
<td>_ios</td>
<td>SDK tutorial. Part of the <ahref="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml">developer menu</a>.</td>
<td>Information for Stacks holders and people curious about what Blockstack does. Appear in the the <ahref="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_org.yml">organization menu</a></td>
<td>Not associated with any repository.</td>
<tr>
<td>_storage</td>
<td>Information for developers using storage in their apps or creating Gaia servers. Appear in the the <ahref="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_storage.yml">storage menu</a></td>
The `_data/cliRef.json` file is generated from the `blockstack-cli` subcommand `docs`. This data file is consumed by the `_includes/commandline.md` file which is used to serve up the reference.
@ -68,7 +221,7 @@ The `_data/cliRef.json` file is generated from the `blockstack-cli` subcommand `
If you run into any problem in the generation usually it results from a problem in the repo. You can make a pull request back to the repo to fix anything.
## Clarity Reference
### Clarity Reference
As of 8/12/19 Clarity is in the [develop](https://github.com/blockstack/blockstack-core/tree/develop) branch of core. You can build the Clarity command line from the Docker image. `core/src/vm/docs/mod.rs`
@ -94,7 +247,16 @@ As of 8/12/19 Clarity is in the [develop](https://github.com/blockstack/blocksta
This generates the JSON source files which are consumed through Liquid templates into markdown.
7. Rebuild the documentation site with Jekyll.
8. Review the changes in the Clarity documentation to ensure that no breaking changes were introduced through code changes.
9. If you find the documentation is no longer formatting correctly or there are errors in the reference, create a PR against the `blockstack-core` repo.
### View and test the clarity cli
You can view [the source code](https://github.com/blockstack/blockstack-core/blob/develop/src/clarity.rs).
@ -131,6 +293,73 @@ You can view [the source code](https://github.com/blockstack/blockstack-core/blo
generate_address to generate a random Stacks public address for testing purposes.
```
## Understand how the shared FAQs work
The FAQ system servers single-sourced content that support the FAQs that appear in blockstack.org, app.co, and stacks.com site. We have FAQs that fall into these categories:
* general
* appusers
* dappdevs
* appminers
* coredevs
* opensource
* miscquest
* wallet (Wallet users)
* tokens (Stacks owners)
FAQs are usually written internally by a team that are unfamiliar with markdown or HTML used in websites. So, FAQs are produced using this process:
1. Draft new or revised FAQs in a Google or Paper document.
2. Review the drafts and approve them.
3. Convert the FAQ document to HTML.
4. Strip out the unnecessary codes such as `id` or `class` designations.
This leaves behind plain html.
5. Add the new FAQs to the `_data/theFAQS.json` file.
Currently this is manually done through cut and paste.
6. Copy the JSON for `appminers` categories to the `_data/appFAQ.json` file.
7. Run the Jekyll build and verify the content builds correctly by viewing this `LOCAL_HOST/faqs/allfaqs`
8. Push your changes to the site and redeploy.
Single sourcing the content ensures that FAQs are the same regardless of where and on which property they appear in. These source files play a role in the FAQ single-sourcing layout:
<table>
<tr>
<th>File </th>
<th>Contains</th>
<th>Purpose</th>
</tr>
<tr>
<td>_faqs/allfaqs.json</td>
<td>Liquid to generate JSON from theFAQS.json</td>
<td>Serves up the FAQs that are consumed by the blockstack.org and stacks.com sites.</td>
</tr>
<tr>
<td>_develop/faq-data.json</td>
<td>Liquid to generate JSON from appFAQ.json.</td>
<td>Serves up the FAQs that are consumed by the app.co site. <br><br>NOTE: App.co was never changed to pull from the same file as blockstack.org. </td>
</tr>
<tr>
<td>_faqs/allFAQs.md</td>
<td>Liquid and headings.</td>
<td>Reads the _data/theFAQs.json and produces a Markdown file for display in our site.</td>
</tr>
<tr>
<td>_data/theFAQs.json</td>
<td>JSON for the FAQS.</td>
<td>Source file for all the FAQs.</td>
</tr>
<tr>
<td>_data/appFAQ.json</td>
<td>JSON for the app mining FAQs.</td>
<td>Source file for the application mining FAQs.</td>
</tr>
<tr>
<td>_develop/appMiningFAQ.md</td>
<td>Liquid to extract the app mining FAQs from the allFAQs.json file.</td>
<td>Display just the app mining FAQs in the docs.</td>
Musce libero nunc, dignissim quis turpis quis, semper vehicula dolor. Suspendisse tincidunt consequat quam, ac posuere leo dapibus id. Cras fringilla convallis elit, at eleifend mi interam.
Nulla non sollicitudin. Morbi sit amet laoreet ipsum, vel pretium mi. Morbi varius, tellus in accumsan blandit, elit ligula eleifend velit, luctus mattis ante nulla condimentum nulla. Etiam vestibulum risus vel arcu elementum eleifend. Cras at dolor eget urna varius faucibus tempus in elit.
## Image Lightbox Example
Nunc porta malesuada porta. Etiam tristique vestibulum dolor at ultricies. Proin hendrerit sapien sed erat fermentum, at commodo velit consectetur.
{% include image.html img="image1.png" style="wide" lightbox="true" alt="Alt for image" caption="Image in lightbox" %}
Etiam vestibulum risus vel arcu elementum eleifend. Cras at dolor eget urna varius faucibus tempus in elit. Cras a dui imperdiet, tempus metus quis, pharetra turpis. Phasellus at massa sit amet ante semper fermentum sed eget lectus. Quisque id dictum magna, et dapibus turpis.
## Example Of Code Block
In accumsan lacus ac neque maximus dictum. Phasellus eleifend leo id mattis bibendum. Curabitur et purus turpis. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae;
Cras at dolor eget urna varius faucibus tempus in elit. Cras a dui imperdiet, tempus metus quis, pharetra turpis. Phasellus at massa sit amet ante semper fermentum sed eget lectus. Quisque id dictum magna turpis.
> Etiam vestibulum risus vel arcu elementum eleifend. Cras at dolor eget urna varius faucibus tempus in elit. Cras a dui imperdiet
In accumsan lacus ac neque maximus dictum. Phasellus eleifend leo id mattis bibendum. Curabitur et purus turpis. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae;
Etiam in fermentum mi. Sed et tempor felis, eu aliquet nisi. Nam eget ullamcorper arcu. Nunc porttitor nisl a dolor blandit, eget consequat sem maximus. Phasellus lacinia quam porta orci malesuada, vel tincidunt.
Moxiegirl
5 years ago
GitHub