Change-Id: If587defdc0bf1d7c5491c328803289b9e75ba918 Reviewed-on: https://gerrit.hackerspace.pl/c/hscloud/+/1148 Reviewed-by: q3k <q3k@hackerspace.pl> |
||
---|---|---|
.. | ||
config | ||
source | ||
tpl | ||
BUILD.bazel | ||
helpers.go | ||
main.go | ||
markdown.go | ||
README.md |
Hackdoc
Hackdoc is a tool to automatically serve documentation based on a checkout of the hscloud source.
Usage
Any Markdown submitted to hscloud is visible via hackdoc. Simply go to https://hackdoc.hackerspace.pl/path/to/markdown.md to see it rendered.
You can pass a ?ref=foo
URL parameter to a hackdoc URL to get it to render a particular vesrion of the hscloud monorepo. For example:
- https://hackdoc.hackerspace.pl/?ref=master for the
master
branch - https://hackdoc.hackerspace.pl/?ref=change/249 for the the source code at change '249'
Special Markdown
We should be accepting a Somewhat Standard Subset Of Markdown. For reference, we're using the blackfriday library with CommonExtensions enabled.
In addition, we also support Table of Contents autorendering, just place the following anywhere in your document to render a TOC:
[TOC]
Local Rendering
To run hackdoc locally on a filesystem checkout (ie. when working on docs, templates, or hackdoc itself), run:
bazel run //devtools/hackdoc -- -hspki_disable -docroot /path/to/hscloud
The output log should tell you where hackdoc just started listening at. Currently this is 127.0.0.1:8080
by default. You can change this by passing a -pub_listen
flag, eg. -pub_listen 127.0.0.1:4242
.