Markdown docs #620
Description
This issue is to track the feasibility of migrating the docs (back to) markdown.
LayerChart and Svelte UX docs used to be primarily in markdown (+page.md) but were migrated to pure Svelte (+page.svelte) years ago due to a multitude of issues:
- Code completion
- Type checking
- Prettier formatting
- Masked errors
- No quickfix (ex. import) / highlighting of unused imports
The general authoring experience of markdown is better though, especially for guides and longer form writing.
MDsvex has an old issue for adding syntax highlighting to markdown. A evidence.dev developer added a comment on how they accomplished this within their extension (which has been now archived).
Regarding prettier, this looks more challenging as both mdx-analyzer and MDsveX have outstanding issues (the former has some upstream issues linked for prettier, mdx-js, remarkjs, and unifiedjs).
More generally, while this repo is currently using MDsveX (albeit only for a few pages now), I am considering switching to MDSX, which I've used on another project. I've had some issues with later versions of MDsveX and is the reason it's left on version 0.12.3 instead of 0.12.6.
I would also move away from Prism and use Shiki for syntax highlighting.
- https://docus.dev/en/essentials/code-blocks
- https://docus.dev/en/essentials/components
- https://vitepress.dev/guide/markdown
- https://observablehq.com/plot/
- https://vitepress.dev/
- https://sveltepress.site/
- https://rive.app/docs/getting-started/introduction
- https://github.com/remarkjs/remark-directive-
- https://remark-mdc.nuxt.space/
- https://starlight.astro.build
- https://www.mintlify.com/
- https://www.fumadocs.dev/docs/headless/mdx/headings
- https://docusaurus.io/docs/markdown-features
- https://content.nuxt.com/
Improvements after switching
- Improve search and include headers/examples (discussion)
- Generate
llms.txt(see also)