Skip to content

[POC] Markdown support#712

Draft
JoergAtGithub wants to merge 1 commit intomixxxdj:mainfrom
JoergAtGithub:markdown_support
Draft

[POC] Markdown support#712
JoergAtGithub wants to merge 1 commit intomixxxdj:mainfrom
JoergAtGithub:markdown_support

Conversation

@JoergAtGithub
Copy link
Member

@JoergAtGithub JoergAtGithub commented Jan 7, 2025

The example-setups page in this PR is generated from MarkDown syntax instead of RST syntax: https://deploy-preview-712--mixxx-manual.netlify.app/chapters/example_setups

There are many warnings about cross-links, but the links seem to work nethertheless.

@JoergAtGithub JoergAtGithub changed the base branch from 2.5 to main January 7, 2025 19:19
@JoergAtGithub JoergAtGithub requested a review from Holzhaus January 8, 2025 19:35
@daschuer
Copy link
Member

This is a nice summary:
https://nikhilakki.in/markdown-vs-restructured-text

@daschuer
Copy link
Member

What is the status here? Is this only about getting cross link check working?

@acolombier
Copy link
Member

Looks like the links are actually working, only seems to get this false positive on the CI, perhaps some settings to tweak?

@JoergAtGithub
Copy link
Member Author

What is the status here? Is this only about getting cross link check working?

This was a prove of concept how to use MarkDown as manual source for mapping pages instead of RST.
For the PoC I selected a page with many different elements and cross links from and to it. This is more than a mapping page will have (usually only links to other manual page but not in the opposite direction). As you can see, most RST formattings could be translated to MD syntax, but not all. The links work, but there I warnings, which I don't understood.

The idea in our monthly call was to store the MD files next to the controller mapping files, that the contributor needs only one PR to one single Repo. This MD file would than be syncronized to the manual repo, using the same process that we've already to get the changelog into the manual.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants