Migrating hardware manual to Markdown (first batch)

[acolombier]

This migration was automated with a Python script, largely written by an AI and manually tweaked.

• AFAIS, there is no (or very limited) translation in the manual, but this remains something to discuss.
• Some build error (notably Non-consecutive header level increase) are existing issue in RST. We can decide to ignore those or fix in the migration.

---

Test

Migrated pages were reviewed side-by-side with the live RST version on the website manual by eyes, so mistake might have sneaked in. When there was too many visual discrepancy, the manual was discarded from this batch, for later review.

Note

• This is the first batch of manual, where no visual regression were found. Note that table column size was not considered as regression and thus the new Markdown manual is not pixel perfect to the previous RST version, as it would look like the auto-sizing algorithm between RST and MD is not the same.
  When the column layout was explicitly, this explicit declaration was kept in Markdown
• Many visual bugs were found in the previous RST version (label not rendering, unclosed formatting, broken links or lists). Most of those were corrected automatically, since Markdown is more permissive than RST, but some are still a problem.

Plan and future steps

The idea is to carry on with the Markdown migration, before those can all moved (at once or by batches) to the main repo, and pulled automatically (either with a repo automation or at build time).
Once moved into the main repo, we will be able to better help contributor to keep the doc up to date and use AI to help reviewing some poor or incomplete documentation, using the actual mapping definition.

Preview available here

[JoergAtGithub]

Please change the target to 2.6, because merging changes from RST to MD would be a maintenance nightmare. Otherwise this looks already good.

[acolombier]

I have rebased the work onto 2.6. I have an AI agent currently fixing all build errors. As mentioned in the description, even if they exist in main/2.6 as RST, they seems to prevent the build in MD and prevent Netlify preview. I will push that as soon as this is completed and we can consider this for merging, potentially with the fix commit cherry picked as separated PR, since it does have larger change impact (e.g PDF summary)

[acolombier]

I have pushed the fix now, so the build is warning-free. Preview is available in https://deploy-preview-867--mixxx-manual.netlify.app/hardware/manuals

I think this can now be considered for merge.

[JoergAtGithub]

This looks already very good, but I noticed an bullet list that didn't appear as before:

american_audio_vms4#deck-controls:

RST:

MD:

[acolombier]

Ah good catch. Yeah, nested bullet points sometimes needs explicit declaration. I will have a look ASAP.
On another note, we can see that this PR will attract conflict very fast (already 4 files). Are we happy to merge it as soon possible or do we want to wait? If the latter, I won't address conflicts for now.

[JoergAtGithub]

Sure I intend to merge this soon, but regressions must be addressed before I can do this.

[acolombier]

Great - let me know if you spot any other regressions!

[acolombier]

On second checks, it looks like this is the opposite:

On Markdown version (this) it renders well:

And it is broken on the current version (RST)

Or did you mean you don't want to see bullet points here?

Looking at the RST, it looks like the bullet points were intended:

[JoergAtGithub]

On second checks, it looks like this is the opposite:

Indeed, I must have mixed up my browser windows.

Please fix the merge conflicts!

[acolombier]

Conflict fixed! I tried to fix some of those broken links when they were trivial too

[JoergAtGithub]

Nearly all pages look like the old ones or are improved. Except the 5 I commented.

[acolombier]

Thanks for the thorough review, also found some issue and pushed fixups. The Numark Mixtrack Pro page appears to be in a weird design style. Probably some follow up cleanup could be useful.

[JoergAtGithub]

Thanks for the thorough review, also found some issue and pushed fixups. The Numark Mixtrack Pro page appears to be in a weird design style. Probably some follow up cleanup could be useful.

Please create an issue for that!

[JoergAtGithub]

LGTM!

[acolombier]

Done in #882

[JoergAtGithub]

Please squash the fixups

[acolombier]

Done!

[Eve00000]

congrats