Markdown docs

[djmitche]

I've gotten a start here to converting the docs to markdown, using mdbook. I've only done the first two pages, but the idea would be to -- eventually -- do them all.

Thoughts:

• mdbook is "skinnable", so we could probably add the site navbar at the top, but probably shouldn't try to get too fancy
• I think we can make the URLs line up, more or less
• I want to do a fairly mechanistic translation right now. Then future PRs can reorg clean things up.
• Since it seems that the site is run out of this branch, we can set things up so that CI checks that mdbook has been run and the results included in a PR. Ideally we'd get to a spot where the generation happens outside of Git (especially as that means contributors don't need to install mdbook), but that can wait.

WDYT? Should I continue?

[lauft]

We have already migrated holidata.net (👉🏻 repo) and timewarrior.net (👉🏻 repo) to Hugo and made good experiences with that. So we planned to proceed with our other sites as well. It seems as if mdbook is a different mean for the same end, having content and layout separated, creating an easier maintainable documentation.

With having already 2 of our 3 main pages migrated to Hugo, I would rather continue with that...
@tbabej what are your thoughts?

[djmitche]

That makes sense to me. I wasn't aware of that effort.

[djmitche]

@svijee did you have a process you followed for that change? Is there a faster way than rewriting every page in markdown? :)

[svijee]

@djmitche I used pandoc for the majority and some custom scripting/manual work to get the rest of it in the correct format. It was somewhat semi-automated.

[tbabej]

@djmitche Thanks for pushing this effort! I have no strong opinions on hugo vs mdbook, and while it is true it's hugo that is used in timewarrior (and keeping the mechanisms same would be nice), there were some rough edges in hugo as far as I can tell. I'll check this out.

In any case, the bulk of the work really isn't in setting up the static site generator, but as last comments highlight, in converting the existing docs to markdown. Couple of months ago, I have started on that effort (copying the hugo-based setup timewarrior had and converting all the pages to markdown through pandoc). The remaining painful part now is going through the autogenerated markdown files and fixing them up (which are mostly correct, but there are always some artifacts from the conversion).

That work can be found on the md-rewrite branch. Perhaps I should open a PR to make it more visible?

[djmitche]

That'd be great -- I was wondering where that work was :)

[tbabej]

This can be now perused and criticized as #303. In another news, I might have a volunteer to help us with the manual parts of the markdown conversion.

[djmitche]

Great on all counts!!