Skip to content
Source code for Blocknet's documentation portal: https://docs.blocknet.co
Branch: master
Clone or download
Latest commit 5e5c48f May 9, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs self host meta images May 9, 2019
snippets designate unfinished files with - prefix May 8, 2019
theme self host meta images May 9, 2019
.gitignore initial portal commit Jan 8, 2019
README.md designate unfinished files with - prefix May 8, 2019
mkdocs.yml glossary, readme, compatibility, update github link May 3, 2019

README.md

Blocknet Documentation

This repository contains the source code for Blocknet's documentation portal. These documents are currently under progressive and iterative development.

Powered by MkDocs and MkDocs Material.

Getting Started

MkDocs supports Python versions 2.7, 3.4, 3.5, 3.6, 3.7 and pypy.

Using Linux or MacOS:

# clone this repo
git clone https://github.com/blocknetdx/documentation.git

# update pip
pip install --upgrade pip

# install mkdocs and mkdocs-material
pip install mkdocs
pip install mkdocs-material

# install required extensions
pip install markdown
pip install fontawesome-markdown
pip install pygments
pip install pymdown-extensions

Run dev server:

# use from within /documentation/
mkdocs server

This will compile the docs and output the localhost address where the changes can be previewed:

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

You can now see the docs at http://127.0.0.1:8000/. This will reload automatically when changes are saved. Note that the address is not always the same so it's best to check the output for the correct address.

Editing

  • Syntax - These documents use Markdown syntax along with additional syntax for specialty formatting:
  • Content
    • For better navigation, instructions for different OS's should be nested in a collapsible panel.
    • Any repeatable sections should be made into a snippet.
    • Page sections should be separated with a diver line ---.
  • Layout - The page meta tags are managed with theme/main.html and styling s managed in docs/css/style.css.
  • Informational Cards:
    • Types - note, abstract, info, tip, warning, danger, bug, example, quote
    • Standard - !!! type "title"
    • No Title - !!! type ""
    • Collapsible (default closed) - ??? type "title"
    • Collapsible (default open) - ???+ type "title"
  • Formatting Conventions:
    • Styling:
      • Italics - Referencing menu/button text (Settings, Submit, Cancel, etc)
      • Bold+Italics - Word emphasis (available balances, fully unlock)
      • Bold - Sub-subsection titles
      • __Bold Bullet Point__
      • inline code - Reference code, commands (servicenode list), calls (dxGetOrders), file contents (ExchangeWallets=), state (finished), parameters (dryrun) , files (blocknetdx.conf), directories (BlocknetDX/)
      • ```code block``` - Multiline code or fule contents or anything that might need to be copied such as single line commands.
    • Images - ![optional alt text](imagelink "optional hover text")
    • Spacing:
      • Do not skip a line after section headers.
      • Tables require a newline above and below them for parsing/formatting.
      • Informational panels require a newline above and below them for parsing/formatting.
      • Lists require a newline above and below them for parsing/formatting.
  • Internal Linking:
    • Correct:
      • [](/folder_path/page)
      • [](/folder_path/page#section)
      • [](/folder_path/page/)
      • [](/folder_path/page/#section)
    • Incorrect:
      • [](folder_path/page)
      • [](folder_path/page#section)
      • [](../folder_path/page)
      • [](../folder_path/page#section)
      • [](/folder_path/page.md)
      • [](/folder_path/page.md#section)
      • [](/folder_path/page.html)
      • [](/folder_path/page.html#section)

See full wiki: [MkDocs]](https://www.mkdocs.org/) | MkDocs Material

Adding Pages

  1. Create a markdown file (.md) within one of the directories in the docs/ folder.
  2. Add a title: and description: at the top of the file.
  3. Add an --8<-- "extras.md" tag at the end of the file.
  4. Add a link to the menu (if needed) by listing it under nav: in mkdocs.yml.
  5. Preview the page to make sure everything is rendering correctly.

Creating and Using Snippets

  1. Create a markdown file (.md) within the snippets/ directory.
  2. Use --8<-- "snippetfilename.md" tag to embed the snippet in a page.
    • The filenames are relative to the snippets/ directory.
  3. Preview the page to make sure everything is rendering correctly.

Publishing

  1. Build the docs with the mkdocs build command.
  2. In the site/ directory, remove any folders and subfolders that begin with -. This prefix is used to flag pages that have not been completed yet.
  3. Deploy site/ contents to staging site for testing.
  4. Deploy site/ contents to https://docs.blocknet.co/.
You can’t perform that action at this time.