From 45d8396e4ef9407ff598fba69e0feb5db9f413c2 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Thu, 16 Jan 2020 13:26:21 -0800 Subject: [PATCH 01/12] Updating README Signed-off-by: Mary Anthony --- README.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9574c2c6..40a633d5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,26 @@ -# README for the documentation site +# README: Overview Documentation Repository +## How the Documentation is Organized -## Building after a fork + + + + + + + + + + + + + + +
DirectoryPurposeNotes
```bash,npm install --save radiks,``````bash,yarn add radiks,```
+ + + +## ## Run locally From eacdab4abd5034e8a30a693fbf74112ca545507a Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Thu, 16 Jan 2020 13:47:08 -0800 Subject: [PATCH 02/12] wip Signed-off-by: Mary Anthony --- README.md | 90 +++++++++++++++++++++++++++++++++++-- _config.yml | 2 +- _posts/2017-05-25-post63.md | 51 --------------------- news/index.html | 49 -------------------- 4 files changed, 88 insertions(+), 104 deletions(-) delete mode 100644 _posts/2017-05-25-post63.md delete mode 100644 news/index.html diff --git a/README.md b/README.md index 40a633d5..21cc0a83 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ ## How the Documentation is Organized + + @@ -9,14 +11,96 @@ - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -
DirectoryNotes
```bash,npm install --save radiks,``````bash,yarn add radiks,```_android
_browser
_commong
_core
_data
_develop
_faqs
_includes
_ios
_layouts
_org
_plugins
_posts
_sass
_storage
assets
exclude
news
+ diff --git a/_config.yml b/_config.yml index 4d55fbde..07bf83fc 100644 --- a/_config.yml +++ b/_config.yml @@ -90,7 +90,7 @@ paginate: 10 paginate_path: "/news/:num/" # Path to post content assets directory i.e post images, pdfs etc -post_assets: /assets/posts/ +# post_assets: /assets/posts/ #keep_files: (`/images/`) diff --git a/_posts/2017-05-25-post63.md b/_posts/2017-05-25-post63.md deleted file mode 100644 index 85eda15d..00000000 --- a/_posts/2017-05-25-post63.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -layout: post -title: Example Post -author: John Black ---- - -## Site tags - - - {% if site.tags contains page.featured.tag %} - **There is at least one** - {% endif %} - - -{{ site.post_assets | absolute_url }} - -{{ page.url }} - -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; - -```html - - - - - - - - -``` - -## Text and Quote -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. diff --git a/news/index.html b/news/index.html deleted file mode 100644 index f6ea6f48..00000000 --- a/news/index.html +++ /dev/null @@ -1,49 +0,0 @@ ---- -layout: default -title: News ---- - -
-
- -

{{ page.title | escape }}

- - {% for post in paginator.posts %} -
- -
-
- {% if page.author %} - {% assign author = site.authors[page.author] %} - {% else %} - {% assign author = site.author %} - {% endif %} - -
- {% if author.github %} - {% avatar {{ author.github }} size=40 %} - {% endif %} -
-
-

{{ post.title }}

-

-
-
-
-
- {{ post.excerpt }} -
-
- Read more → -
- -
- {% endfor %} - - {% include paginate-blog.html %} - -
-
From 4905b0371e47f0b51fe9718e3f07f9fd5f18354e Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Thu, 16 Jan 2020 13:54:09 -0800 Subject: [PATCH 03/12] Updating the README Signed-off-by: Mary Anthony --- _config.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_config.yml b/_config.yml index 07bf83fc..10a8d704 100644 --- a/_config.yml +++ b/_config.yml @@ -84,13 +84,13 @@ google: container_id: GTM-TPGGRT5 # Number of posts displayed on blog page -paginate: 10 +# paginate: 10 # Blog path -paginate_path: "/news/:num/" +# paginate_path: "/news/:num/" -# Path to post content assets directory i.e post images, pdfs etc -# post_assets: /assets/posts/ +# Path to content assets directory i.e post images, pdfs etc +post_assets: /assets/img/ #keep_files: (`/images/`) From 95def580840397368824da6d2a561faa800474d5 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Fri, 17 Jan 2020 09:47:16 -0800 Subject: [PATCH 04/12] Updating all the readme material Signed-off-by: Mary Anthony --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/README.md b/README.md index 21cc0a83..eea82ee2 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,59 @@ ## How the Documentation is Organized +Directories that contain only content + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DirectoryPurposeTechnical Repo(s)
_androidSDK tutorial. Part of the [developer menu](https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml).
_browser
_commong
_core
_develop
_includes
_ios
_org
_storage
From 4156d10e65f44fb119f9da9b6194cdcbd9067239 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Fri, 17 Jan 2020 09:59:16 -0800 Subject: [PATCH 05/12] Pushing live Signed-off-by: Mary Anthony --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index eea82ee2..4273908d 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Directories that contain only content - + From 1d76e80414fd8c4fa96968196b83f45e6a8e48e9 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Tue, 21 Jan 2020 13:22:24 -0800 Subject: [PATCH 06/12] WIP Signed-off-by: Mary Anthony --- README.md | 68 ++++++++++++------------------------------------------- 1 file changed, 14 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 4273908d..4b35be5b 100644 --- a/README.md +++ b/README.md @@ -14,37 +14,37 @@ Directories that contain only content - + - - + + - - - + + + - - + + - - + + - + - + @@ -53,7 +53,7 @@ Directories that contain only content - +
_androidSDK tutorial. Part of the [developer menu](https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml).SDK tutorial. Part of the developer menu.
_android SDK tutorial. Part of the developer menu.https://github.com/blockstack/blockstack-android
_browserInformation 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 user menu. The three tutorials that appear in the developer menu There is an outstanding issue to move these.https://github.com/blockstack/blockstack-browser
_commong_commonContains several shell fills 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.Each of these references are generated by their respective repos, core.blockstack.org from blockstack-core, Javascript docs from the blockstack.js and so forth.
_coreInformation for wallet, blockchain, or Clarity developers -- including Atlas, BNS, and so forth. This content STILL needs to be synced with the master docs subdirectory in blockstack-core. blockstack-core
_developInformation for application miners covers using the Javascript library, our mobile SDKs, and the concepts hat support them. Navigation controlled by developer menu This information was never associated with a single repo. Much of it does rely heavily onhttps://github.com/blockstack/blockstack.js.
_includesInformation reused (markdown or html) in many places, common html used in pages and notes.
_ios https://github.com/blockstack/blockstack-ios
_org
_storage https://github.com/blockstack/blockstack-gaia
@@ -64,22 +64,7 @@ Directories that contain only content Notes - _android - - - - - _browser - - - - - _commong - - - - - _core + _common @@ -88,11 +73,6 @@ Directories that contain only content - - _develop - - - _faqs @@ -103,21 +83,11 @@ Directories that contain only content - - _ios - - - _layouts - - _org - - - _plugins @@ -133,11 +103,6 @@ Directories that contain only content - - _storage - - - assets @@ -147,11 +112,6 @@ Directories that contain only content exclude - - - news - - From 7666248fe71fb61522be77414c47169b01a8156c Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Wed, 22 Jan 2020 09:28:28 -0800 Subject: [PATCH 07/12] wip Signed-off-by: Mary Anthony --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4b35be5b..3658a25a 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Directories that contain only content _common - Contains several shell fills 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. + 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. Each of these references are generated by their respective repos, core.blockstack.org from blockstack-core, Javascript docs from the blockstack.js and so forth. @@ -43,13 +43,13 @@ Directories that contain only content _ios - + SDK tutorial. Part of the developer menu. https://github.com/blockstack/blockstack-ios _org - - + Information for Stacks holders and people curious about what Blockstack does. User docs controlled by in the the organization menu + Not associated with any repository. _storage From 926cf22a91bfc80fd8824778c8f5f1f1e7322b45 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Wed, 22 Jan 2020 10:33:43 -0800 Subject: [PATCH 08/12] wip Signed-off-by: Mary Anthony --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 3658a25a..6022faa7 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ ## How the Documentation is Organized -Directories that contain only content +Directories that contain information used to build content. @@ -34,7 +34,12 @@ Directories that contain only content - + + + + + + @@ -48,11 +53,11 @@ Directories that contain only content - + - +
_develop Information for application miners covers using the Javascript library, our mobile SDKs, and the concepts hat support them. Navigation controlled by developer menu This information was never associated with a single repo. Much of it does rely heavily onhttps://github.com/blockstack/blockstack.js.This information was never associated with a single repo. Much of it does rely heavily on https://github.com/blockstack/blockstack.js.
_faqsContains a JSON source file for all the FAQs. The JSON in this directory
_includes
_orgInformation for Stacks holders and people curious about what Blockstack does. User docs controlled by in the the organization menuInformation for Stacks holders and people curious about what Blockstack does. Appear in the the organization menu Not associated with any repository.
_storageInformation for developers using storage in their apps or creating Gaia servers. Appear in the the storage menu https://github.com/blockstack/blockstack-gaia
@@ -73,11 +78,7 @@ Directories that contain only content - - _faqs - - - + _includes @@ -247,6 +248,58 @@ 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. JSON files are created by the Jekyll build and served through the documentation site. Single sourcing the content ensures that FAQs are the same regardless of which property they appear in. These files participate in the FAQ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
File ContainsPurpose
_faqs/allfaqs.jsonLiquid to generate JSON from theFAQS.jsonServes up the FAQs that are consumed by the blockstack.org and stacks.com sites.
_develop/faq-data.jsonLiquid to generate JSON from appFAQ.json.Serves up the FAQs that are consumed by the app.co site.

NOTE: App.co was never changed to pull from the same file as blockstack.org.
_faqs/allFAQs.mdLiquid and headings.Reads the _data/theFAQs.json and produces a Markdown file for display in our site.
_data/theFAQs.jsonJSON for the FAQS.Source file for all the FAQs.
_data/appFAQ.jsonJSON for the app mining FAQs.Source file for the application mining FAQs.
_develop/appMiningFAQ.mdLiquid to extract the app mining FAQs from the allFAQs.json file.Display just the app mining FAQs in the docs.
+ +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 # Technology Reference From cc13798cddb7d269181f47eb6289bf34852f6dff Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Wed, 22 Jan 2020 20:29:20 -0800 Subject: [PATCH 09/12] wip Signed-off-by: Mary Anthony --- README.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 6022faa7..2cd56008 100644 --- a/README.md +++ b/README.md @@ -38,13 +38,13 @@ Directories that contain information used to build content. _faqs - Contains a JSON source file for all the FAQs. The JSON in this directory - + Contains files for single-sourcing all the FAQs. The Blockstack docs has a single page that lists all the faqs; then several pages in different sections re-use this information. See the FAQs section below for detail about how these files figure into FAQS. + Not related to repo. _includes - Information reused (markdown or html) in many places, common html used in pages and notes. - + Information reused (markdown or html) in many places, common html used in pages and notes. + These files don't correspond to a repository. _ios @@ -68,14 +68,9 @@ Directories that contain information used to build content. Purpose Notes - - _common - - - _data - + Source files for the FAQS. @@ -250,7 +245,19 @@ You can view [the source code](https://github.com/blockstack/blockstack-core/blo ## 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. JSON files are created by the Jekyll build and served through the documentation site. Single sourcing the content ensures that FAQs are the same regardless of which property they appear in. These files participate in the FAQ +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) + +FAQ content is created by the Jekyll build and served throughout the documentation site. Single sourcing the content ensures that FAQs are the same regardless of where and on which property they appear in. These files participate in the FAQ: @@ -299,7 +306,8 @@ FAQs are usually written internally by a team that are unfamiliar with markdown 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 +6. Copy the JSON for `appminers` categories to the `_data/appFAQ.json` file. + # Technology Reference From a1eae75339f3229bec4d348ded27bacf2371401b Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Wed, 22 Jan 2020 20:32:54 -0800 Subject: [PATCH 10/12] WIP Signed-off-by: Mary Anthony --- README.md | 34 +++++++--------------------------- 1 file changed, 7 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 2cd56008..522bcfca 100644 --- a/README.md +++ b/README.md @@ -62,52 +62,32 @@ Directories that contain information used to build content.
+These are the other directories in the site structure: + - - - - - - - - - + - - + - - + - - - - - - - + - - - - - - - +
Directory PurposeNotes
_dataSource files for the FAQS.
_includesJSON source files for the FAQS, CLI, and clarity reference. Menu configurations YAML files. The CSV file with the glossary.
_layoutsLayouts for various pages. The community layout is significantly different from the other layouts.
_pluginsCode files for plugins.
_posts
_sassStyle folder including customizations.
assets
excludeSupport for the docs templates.
From 62dd1202ac68b659676cf9009151efb05d0587cd Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Wed, 22 Jan 2020 20:35:26 -0800 Subject: [PATCH 11/12] wip Signed-off-by: Mary Anthony --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 522bcfca..71dd9a18 100644 --- a/README.md +++ b/README.md @@ -70,23 +70,23 @@ These are the other directories in the site structure: Purpose - _data + _data JSON source files for the FAQS, CLI, and clarity reference. Menu configurations YAML files. The CSV file with the glossary. - _layouts + _layouts Layouts for various pages. The community layout is significantly different from the other layouts. - _plugins + _plugins Code files for plugins. - _sass + _sass Style folder including customizations. - assets + assets Support for the docs templates. From 0c9d7692b55be0d2a51ce89850e2d3202070fa65 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Fri, 24 Jan 2020 06:54:17 -0800 Subject: [PATCH 12/12] updating Signed-off-by: Mary Anthony --- README.md | 156 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 114 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 71dd9a18..55b4b296 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,51 @@ # README: Overview Documentation Repository -## How the Documentation is Organized +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. + + + + + + + + + + + + + + + + + + + + + + + + + + +
UsersDescription
STX holdersUsers 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.
DApp usersUsers 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.
Dapp developers or DApp minersUsers 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.
Hub ProvidersUsers 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.
Core service programmersThese 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.
+ +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. @@ -93,19 +137,16 @@ These are the other directories in the site structure: -## +## Building the documentation source for display + +If you are making significant changes to the documentation, you should build and view the entire set locally before submitting a PR. ## Run locally To run locally: -1. Get the content from the downstream repos. - - ``` - ./get-content.sh - ``` - -3. Build and serve locally. +1. Install Jekyll into your workstation environment +2. Build and serve locally. ``` bundle exec jekyll serve --config _config.yml,staticman.yml @@ -116,35 +157,55 @@ To run locally: ``` JEKYLL_ENV=production bundle exec jekyll serve --config _config.yml ``` - -## Deploy via Netlify - -To deploy to Netlify: - -1. Build the site. - - ``` - JEKYLL_ENV=production bundle exec jekyll build --config _config.yml - ``` -2. Force add the `_site` directory. - - ``` - git push -f origin - ``` - ## Test a Deploy with Surge +You can also do a test deploy using a tool like [Surge](https://surge.sh/). ``` cd _site surge ``` +Make sure you delete the deployed Surge domain when you are done. Using the `teardown` command. + ``` -surge --domain raspy-songs.surge.sh -``` + surge – single command web publishing. (v0.21.3) + + Usage: + surge + + Options: + -a, --add adds user to list of collaborators (email address) + -r, --remove removes user from list of collaborators (email address) + -V, --version show the version number + -h, --help show this help message + + Additional commands: + surge whoami show who you are logged in as + surge logout expire local token + surge login only performs authentication step + surge list list all domains you have access to + surge teardown tear down a published project + surge plan set account plan + + Guides: + Getting started surge.sh/help/getting-started-with-surge + Custom domains surge.sh/help/adding-a-custom-domain + Additional help surge.sh/help + + When in doubt, run surge from within your project directory. + ``` + +## Deployment of the site + +The documentation is deployed to Netlify using the following command: + + ``` + JEKYLL_ENV=production bundle exec jekyll build --config _config.yml + +## Generated documentation -# To generate the CLI json manually +### To generate the CLI json manually 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. @@ -160,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` @@ -186,7 +247,16 @@ As of 8/12/19 Clarity is in the [develop](https://github.com/blockstack/blocksta ``` $ docker run --name docsbuild -it blockstack-test blockstack-core docgen | jsonpp > ~/repos/docs.blockstack/_data/clarityRef.json ``` -## To view the clarity cli + + 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). @@ -237,7 +307,20 @@ The FAQ system servers single-sourced content that support the FAQs that appear * wallet (Wallet users) * tokens (Stacks owners) -FAQ content is created by the Jekyll build and served throughout the documentation site. Single sourcing the content ensures that FAQs are the same regardless of where and on which property they appear in. These files participate in the FAQ: +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: @@ -277,17 +360,6 @@ FAQ content is created by the Jekyll build and served throughout the documentati
-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. - # Technology Reference