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/github.com/russross/blackfriday/v2) library with [CommonExtensions](https://godoc.org/github.com/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`.