mirror of https://gerrit.hackerspace.pl/hscloud
34 lines
1.4 KiB
Markdown
34 lines
1.4 KiB
Markdown
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](https://godoc.org/gopkg.in/russross/blackfriday.v2) library with [CommonExtensions](https://godoc.org/gopkg.in/russross/blackfriday.v2#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`.
|