Prepare for translation

[marmarek]

This is similar PR to QubesOS/qubesos.github.io#153
The intention is to do all the ground work, without actually enabling the translations yet. The changes are:

• Atx-style headings everywhere
• lists syntax fixes all over the places (extra spaces etc)
• trailing whitespaces fixes
• code blocks with ```, not only indentation (is it necessary to have it indented too?)
• add 'lang' and 'ref' attributes to the frontmatter - this is result of running a script I haven't yet included in qubesos.github.io (but it is at https://github.com/marmarek/qubesos.github.io/pull/5/files#diff-9330f247ff2b21fa55e4ad481c0bb6eebe634fee305513ae367693719b428f99)
• some pages use custom page-specific layout basically importing the content from the main repo. Specifically:
  • introduction/experts.md
  • doc.md
• pages that now "dynamic" content have generated by a specific layout instead instead of using liquid template in this repo; the reason for this is to eliminate liquid templates from qubes-doc repo, to have pure (translatable) content here.
  • user/hardware/hcl_listing.md (renamed from hcl.html)
  • project-security/canaries.md
  • project-security/security-bulletins.md
  • project-security/xsa.md
  • developer/general/style-guide.md
• rename files to not contain dots (problematic with transifex api)

This all is work done by @maiska (marmarek#3), with git commits cleaned up. Thanks!

[marmarek]

testdeploy

[marmarek]

testdeploy

[marmarek]

I went through a diff of resulting HTML files (but stripping actual HTML tags for the diff purpose - using w3m -dump) and I think this is correct now. I've verified there are no unintended content changes, only some formatting changes which in most cases are actual improvements (and in other are neutral).
The actual diff on raw HTML files is rather huge and there is a small chance that some formatting changes I've excluded when comparing are not intended, though.

The command I used to diff is:

find old -type f -print -exec bash -c 'diff -uw <(w3m -dump "{}") <(w3m -dump $(sed "s:old:new:" <<<"{}"))' \; > site.diff

where the old version (built from the master branch) is in old dir and the new version is in new dir.

[marmarek]

testdeploy

[andrewdavidwong]

code blocks with ```, not only indentation (is it necessary to have it indented too?)

No, it should be one or the other, not both (except when the code block appears inside of a list, in which case both the fence and the code should be indented to the same level). Doing both results in a code block where each line is indented, which we don't want. This page contains several examples: https://wwwpreview.qubes-os.org/doc/automated-tests/

Can you remove the excess indentation in cases where ``` fences have been added?

[andrewdavidwong]

Where can I find the live website result from testdeploy? I can't remember the URL.

Never mind, found it from the button below.

[andrewdavidwong]

This PR causes some, but not all, of the items in the ToC to be indented by one: https://wwwpreview.qubes-os.org/doc/

I can see why, but I don't think the indentation is desired on this page, because these are all actually supposed to be at the same level. It's just that some sections are organized with subheadings, while others aren't. However, it's not that big of a deal, so if you prefer it this way, it's fine.

[andrewdavidwong]

Do I have to worry about things like ref: 29 as I'm maintaining the documentation? For example, if I add/modify/remove a page, do I have to somehow account for these references, or will they be handled automatically?

[marmarek]

This PR causes some, but not all, of the items in the ToC to be indented by one: https://wwwpreview.qubes-os.org/doc/

I don't think that matter that much. In any case, I'd like to have this page automatically generated anyway, so the current state is rather temporary.

Do I have to worry about things like ref: 29 as I'm maintaining the documentation? For example, if I add/modify/remove a page, do I have to somehow account for these references, or will they be handled automatically?

You don't need to worry, it will be handled automatically. One thing that is necessary is to remove it if you ever make a copy of a page (there must be no duplicates).

[andrewdavidwong]

@marmarek, is this merge conflict from #1125?

[andrewdavidwong]

is this merge conflict from #1125?

Ah yes, it is. In the interest of avoiding further merge conflicts and fixing QubesOS/qubes-issues#6489, I'm going to merge this now (keeping the new changes from #1125).

However, I still think the code block issue should be fixed.