Not exactly a Swift question, but it is a DocC question.
Out of curiosity does anyone know of any existing work to make a plugin that would handle docc style markdown for remark?
more about remark plugins
I'm in a position where if I could point a SSG (static site generator) that uses remark as its parser at an existing docc folder it would be really really handy.
(Note: didn't find any docc flavored parsers with npm search either)
I'm not aware of any - I've not used remark and am unfamiliar with what it's doing or how it does its work. DocC markdown is mostly GfM with a few minor tweaks added - there's term list support, and probably others that I haven't deeply tracked, but there's also the whole linking structure with symbols and articles (using either the double backticks `` or the doc:... references) that I'm not sure how you'd wrangle - the mixing of symbols from the compiler (if you're doing API reference docs) and the articles or extension pages into JSON data structures is the core of what docc convert does.
What's the goal of what you're trying to do with remark? I can at least share how I tackle similar situations if it'd help.
Thank you for the reply!
This is all a very hypothetical at the moment so I was looking to see if someone else had had the need. No one should spend extra time on this. I was really just looking to see if someone had already.
So TL;DR don't worry about it.
But the motivation for the question...
Really the problem is if one is writing articles / tutorials where should they live? What system should be used to make them? If one uses DocC they're sort of locked up in DocC land. Yes there is the themes capacity, but that still leaves anything written in DocC mired in the actual code repo and sort of living a bolted on existence for any website they try to integrate into.
Could one use some CI script to push docc articles and tutorials verbatim from a Swift repo in their pre-transformed state so a different SSG could do all the formatting, etc? Or could one just generally use some of the conveniences that docc flavored syntax has added in another context so one doesn't have to keep syntax switching?
One possible SSG is Astro, which uses Typescript and Zod to get some type safety. My understanding is Astro has remark create an AST from markdown and that AST gets handed to a sibling package rehype to generate the HTML. Astro can also handle json files for structured content, so that is one path forward for some of the docc content.
But going down this path means a lot of quality time rewriting in Javascript/Typescript what's already been written in Swift and I'm not sure I'm that committed to DocC or Astro yet.
Thank you though!