miked

Here's the best I can come up with so far, that looks possible: Required: Permanent links, TOC, searchable Desired: Minimal source structure, hard to break. Not important: Platform independence (documentation source need not work as-is with other software). For permanent links, we have fixed file names, and anchor IDs embedded in the source. Something like: [permalink]: how-to-boot # How to boot? Insert SD card... We process the output of mkdocs so that where "permalink" was in the source, the next anchor is replaced with what we specified. The link source markdown could be generated by our scripts, then put in the source document. The writer then wouldn't need to create the link text. If it is missing it won't break anything. The rules for editing docs, to avoid breaking links, are: - Do not change file names - Do not edit permalink line, or separate it from the section's text - Do not move a permalink'd section to another file ([id] or [anchor] might be preferred over [permalink]. The tag could go after the title if preferred. I think this uses valid markdown syntax.) Edit: These tags are optional, only necessary if we have external links to the documentation section, and if the section title is changed and no longer matches what was linked. If we wanted to avoid cluttering the source with these tags, we could have our scripts generate these lines only for any links that were in the previous mkdocs output but not the new one, indicating a possible change to the section title. These tags would essentially indicate the original section title. [permalink]: how-to-boot # Booting your device After ensuring your power supply...

I'll experiment with some ideas I have for persistent links. To let the public edit documentation, couldn't you let them edit a branch in github (or github wiki), and check that it doesn't break everything whenever you want to pull their changes?

There are a few tasks mentioned in this thread: - Documentation html software and layout (mkdocs output, toc, search etc.) - Edit Armbian.com to integrate the new docs location. Also link to documentation pdf somewhere. - Auto generate and process the docs/pdf on github documentation commits (now do this on wiki edits?) - Tweak pdf generation to look like a professional book. - Reordering/structuring documentation so both newbs and experts can easily get to what they need (is this a separate task?) - General documentation rewriting and additions (these are separate tasks) As far as I know, all of these tasks are being worked on. I'm not currently working on any of them, let me know if I can help! I got confused about this too. But it looks like GitHub wiki will be used as the documentation source (markdown), it will still be processed into pretty html and pdf for armbian.com?

I would totally do that! It might also identify some easy-to-fix problems that could be a good place to start contributing code.

Sorry if getting off topic, but... a relay does that. Search "arduino relay" on ebay (< $2) or amazon etc for the easiest solution. Cut the live wire of a power cord and put the relay module in between.

I did a bit of experimentation and have the following suggestions: 1. On http://www.armbian.com/change "Getting Started" to "Documentation". Currently all documentation is under "getting started" which isn't an intuitive place to look for advanced stuff. However since you want a clear "where to start" sign that stands out to new visitors, we could have a prominent "Getting Started: Everything you need to get Armbian up and running" icon/link/banner stickied near the top of the Home page (and maybe Downloads page if people are directly linked there from external sites). It should take you to a documentation page that starts with an outline (with links) of the main steps a complete novice would take. 2. If the html docs are going to be mainly mkdocs output with some post-processing, I would try to put the output underneath the Armbian nav bar, using a theme that has the Documentation navigation on a left sidebar to avoid crowding the top. Theme readthedocs does this. It should be possible to use html <embed> to shove the mkdocs webpage into the Armbian web page. Unless someone really wants to tweak the theme and process the output to look perfect, maybe as little as changing the theme's colors will be enough to make it look good. Edit: That is, either you could let mkdocs use the whole browser window, which is not ideal because it looks like the documentation is a different site. Or leave mkdocs output as a full webpage and embed it, which I think would be easiest to try. Or process the output a lot so that you combine the Armbian page and the mkdocs output into one generated page, which should be more work but give you more control.

I see Tido is currently taking a look at it. Otherwise I'd give it a shot. Are there unclaimed tasks suitable for newbs who would like to start contributing but have little experience?