techniq
Markdown docs
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.
Improvements after switching
- [ ] Improve search and include headers/examples (discussion)
- [ ] Generate
llms.txt(see also)
The MDSX project on GitHub seems to be absent (404), which is weird. There hasn't been much activity recently – just one year ago, and then a single commit two months ago. If support were to be dropped, migrating everything to MDSX could be risky.
In contrast, MDsvex appears to be a more robust choice. It's officially recommended by the Svelte team and has significantly more downloads (47000 vs 390).
Regardless of the chosen path, I'd be happy to help with the migration by opening a pull request.
Thanks @l0uisgrange 🫶
MDSX was created by @huntabyte and @AdrianGonz97 (possibly others) and is used on shadcn-svelte, bits-ui, runed and other svecosystem packages. I also use it on https://zipline.ai/ docs (which are still in progress).
I chat with Hunter on Discord and they're planning to open source the project after it's been migrated from a Svelte preprocessor to a Vite plugin. I'm not sure the timeline on this change, but the impact downstream should be minimal.
I really liked mdsvex and have been using it for years, but ran into some issues with recent versions and also have been looking to move to Shiki highlighter. Neither of these are impossible to do with mdsvex, but it felt like the project was idle on updates for a while and started looking around, and really liked mdsx.
Either mdsvex or mdsx would serve us well. The bigger challenge is improving the authoring experience with markdown and Svelte, which will likely require a custom VSCode plugin or upstream Svelte plugin improvements.
I started a thread on bluesky to see if anyone has any thoughts, and created this issue to capture findings and progress.
I think a great first step would be to migrate from Prism to Shiki syntax highlighting. A few places that need updated:
- Upstream in Svelte UX codePreview plugin
- Preview component
- Code component
- Remove prism theme in layout
also have this issue with some useful links (but might be a little dated).
Hi @techniq 👋,
Thank you for the explanation. I didn't know the project had this team behind it, this is great news!
I think a great first step would be to migrate from Prism to Shiki syntax highlighting. A few places that need updated: ...
I will open a pull request to work on this asap ⚡️.