# Static site generation from HackMD content
## Intent
A 'static site generator' (SSG) is a tool which takes a number of content files and uses configuration files as the parameters for their translation into HTML to provide a complete, structured, multi-page website without dynamically created content. [Here's a fuller explainer](https://davidwalsh.name/introduction-static-site-generators).
Where responsive elements are required, these are typically provided using javascript.
This document explores what would be needed to generate such sites from HackMD files.
## Why is this of interest or importance?
The motivation here is to outline the possibillity of producing a static 'knowledge' site from materials that are composed in HackMD.
That at intervals, it might be useful to publish a 'current version' of those pages from the hackMD wiki which are considered 'stable', in a format which is not bounded by HackMD's UI / branding.
The format desirable for this might be a 'simplified', 'article only' approach suitable for interested readers looking for the content, not wanting to be distracted / made nervous by editing tools (a common issue with wiki presentations).
This document is about an approach to that.

## Overview
- HackMD (HMD hereafter) is a powerful, web-based document creation and editing tool with usable collaboration features.
- Text content is produced in markdown, but there are a number of other translation tools to give a very useful range of content types including graphs and diagrams.
- HMD has a built-in html export tool (with two choices 'HTML' and 'raw HTML' - see below).
- HMD has fairly granular team and permissions capacities.
- It looks as if HMD has a [API interface, but from the GitHub](https://github.com/hackmdio/api-client), it is hard to find out much.
- Likewise, there appears to be a [HackMD command line tool](https://github.com/hackmdio/hackmd-cli) which is more fully documented.
- HMD has a simple wiki-like link / new page building capability.

These features would seem to form the basis for a workable proposition to build a static.

There is a repo on the [HMD github](https://github.com/hackmdio) that promises to do something aloing these lines - [How to make a doc site on GitHub with HackMD](https://github.com/hackmdio/docs-with-hackmd)- last commit 2 years ago. This uses a popular SSG tool called [Jekyll](https://programminghistorian.org/en/lessons/building-static-sites-with-jekyll-github-pages) and HMD's built-in [sync to gitHub tool](https://hackmd.io/c/tutorials/%2Fs%2Flink-with-github). There is another repo that looks as if it is simply about allowing for custom Jekyll themes - although the readMe is not very helpful - [A GitHub Action for Custom Jekyll Builds on GitHub Pages](https://github.com/hackmdio/jekyll-deploy-gh-pages) - last commit 2 years ago. The lack of recent activity does not imbue confidence, but this may be good enough to begin with. However, HMD is simply used as a markdown editor, losing both rich content types and internal wiki links.

## Typical static site generation process
- content files are created - typically using markdown.
- these include 'front matter' - meta-data, typically written in a YAML or TOML code block, which provides information used during the site building process. Different site generators provide different levels of sophistication.
- configuration files are created - typically using YAML or TOML
- these contain several kinds of information
- base url and other site defining characteristics
- content structuring information, if any. This might specify the existence of 'post' and 'page' type content, as with a typical blog, but any desired categorisation is possible
- HTML templates relating to page types. For a blog site, there might be 'index', 'post' and 'page' templates. There is also typically at least one 'list' type template (NB: for a static site, dynamic 'search' tools are not possible. Instead, SSGs pre-compile pages for searches of known kinds - categories, tags, content types. live sorting of such lists is also not possible, so if different sortings are required, these also need to be pre-specified).
- The above provides the minimum necessary material, but for more sophistication, additional files are often provided
- 'partial' templates to support site-wide features like headers, navigation, footers etc
- javascript inclusions in templates (potentially in content, although this is not normally a feature)
- CSS files
- Editable 'theme' collections of templates and configuration files
- A 'build' tool is applied to the collection of files - typically stored in a Git repo. a single invocation of such a tool might provide both site building and deployment , or several tools might be needed.
- either through a command-line
- or through a git-platform 'pipeline' process
- Sites are either self-hosted or deployed to a cloud-server. [Netlify and others](https://www.hostingadvice.com/how-to/best-static-web-hosting/) provide free hosting for static sites with even fairly large bandwidth usage.

## How might the above be achieved using HackMD?
### Overview
Clearly, since HMD already provides for sophisticated HTML production, 'understanding' a variety of markup tools to provide a variety of content types, the workflow with HMD would differ a little from that described above.
In an HMD context an SSG tool would most usefully take HMD-produced HTML files as its input files, rather than raw markdown text files.
- config and template files, presumably created in HMD, would be fairly straightforward.
- site-wide material like header, footers, navigation would need to be inserted.
- Handily, HMD's 'raw HTML' export option produces a 'content only' HTML markup as a single `<div>` with `<span>` elements.
- The 'complete' HTML export links to some fairly detailed stylesheets and has a table-of-contents built-in.
- List pages would need to be compiled and created.
- HMD's sync to Github tools would be used - 'pull' for editing existing content, 'push' for committing new content
- Commits could be used to trigger an automatic site build/deploy pipeline.
### Issues

- Neither HTML export option builds links to 'internal' HMD pages. An `<a>` tag *is* produced, with a null reference - so that it *is* possible to know that a link is intended. Unless the visible linked text is the title of a page, though (this is not a requirement in HMD), it would be impossible (?) to determine which file to link to. Links to HackMD pages *not* published would result in 'page missing' screens unless amended by the SSG.
- Changes to HMD's html export routines could break the generation workflow/algorithms.

## Alternative approaches
Theses are alternative approaches to content creation and editing that feed into SSG workflows. As such, they would not support HMD's wide range of markup translation capacities, and also will be unlikely to offer wiki link creation tools.
[headless CMS](https://alternativeto.net/tag/content-as-a-service/) - these manage content in a structured way (JSON), but don't assume anything abhout a front end. [Sanity.io](https://alternativeto.net/software/sanity-io/about/) is an example that is open-source.
[Prose content authoring](http://prose.io/#about)