Use markdown sources

[memowe]

Thanks for all your effort in this important project!

I think it would be great to have the book‘s content as markdown files instead of HTML files:

Pros:

1. It would make contributions much easier as it wouldn‘t require web authoring skills.
2. It would make diffs much more readable.
3. With pandoc and custom templates it would make exporting HTML, PDF or EPUB a very transparent process.

Cons:

1. Lots of work. Especially when it‘s a requirement to produce (almost) the same HTML result as before.
2. ...?

What do you think about it?

[memowe]

One step back: let's discuss the idea here. :)

[xogcox]

Here is the current situation. I've written a markdown version (which was PR #35). Everything in and below the /markdown directory is based on this markdown, and in particular, the markdown/generated_html directory contains the HTML that the markdown generates.

Unfortunately, it's not possible to write idiomatic* markdown that generates exactly the HTML of the original website. So there are differences between the markdown-generated HTML and the current website HTML (in the /docs directory). That means that although there is a markdown version, it isn't being used.

(*Side note: I say "idiomatic" because markdown lets you include arbitrary HTML as an "escape hatch" for things you can't express in pure markdown. So technically you could write a markdown file that just uses the original website's HTML whenever there's a slight difference, but it would end up being full of raw HTML, which would be as difficult to read and edit as HTML, defeating the purpose of using markdown.)

Presumably, the point of having a markdown version is to use it for generating the HTML, so that you can edit the markdown instead of editing the HTML So the next step is to make a decision: Is it acceptable to replace the current website HTML with the markdown-generated version? If not, what are the obstacles to this? Or is there some other way forward?

To help the decision, I've written PR #41, which is a breakdown of the changes to the original HTML that would be necessary to make it match the markdown-generated HTML. This PR makes step-by-step changes so that the HTML in /docs is the same is the HTML in markdown/generated_html. To switch over, you could merge this PR, and then the final step would be to delete the generated_html directory and output the HTML directly into /docs.

Recently, there's been a PR (#46) intended as an update to the website content, but that edits the markdown and markdown-generated HTML, not the HTML in /docs. Unfortunately, since the markdown-generated HTML is in a limbo state, where it exists but isn't being used, the PR won't actually change the website. You'd have to change the HTML in /docs together. At the moment, to keep the markdown and live website consistent, any changes have to be made to both versions, which is somewhat awkward.

So please comment on what you think should be done with the markdown, or if you have any questions!

[xogcox]

I'm sorry for the long walls of text and multiple comments, but I'd really like some feedback: what do you feel about using markdown, of the following options?

1. I'd like to start using markdown instead of directly editing HTML, as soon as possible.
2. I'd like to use markdown instead of raw HTML if possible, but there are obstacles in the way.
3. I want the markdown and HTML to both be kept, but to be separate.
4. I don't have a definite opinion.
5. Other things have greater priority and I don't feel the need to consider it.
6. The markdown directory is more trouble than it's worth, and should be deleted.
7. Some other option not listed.

I'm happy to accommodate whatever people want, but it would help to know what the situation is.

[memowe]

1. :)

[smith558]

(Ideally, there should be an automatic deployment via GitHub Actions that generates an up-to-date HTML upon each merge to master)

[maueroats]

Option 1.

I personally don't think this repo has enough stars to be worried about the minor breakage that might occur from small mistakes in the translation process. Fix them as you hear and move forward.

Agreed about the GHA to auto-generate HTML.

Markdown as the single source of truth seems best to me.

[simon-nicholls]

#41 sounds very promising in terms of matching the HTML output