"AI-readable Markdown" — can't we just say "Markdown"? I'm serious about this, why are we focussing on making things accessible to AI when they should just be machine-readable and accessible to human beings in the first place? No need to taint this by bringing AI into it.
show comments
pomber
Nice! Do you think it could be adapted to other docs sites?
I made a small clone of the tutorials section (https://clone-swiftui-tutorial.vercel.app/) where the content is already Markdown (and use codehike to turn the markdown into a rich UI). This made me realize that codehike is AI-friendly, in the sense that even for non-linear UIs the original content is still AI-readable Markdown.
qazxcvbnmlp
Great promise; sometimes need to reference docs to build context.
I looked at the examples you posted and did a quick glance. For example
To achieve its goal I would be worried that it dropped the verbatim function signature. Claude still figured it out, but for more obscure stuff that could be an issue.
show comments
Someone
Hm, I would have extracted the markdown from the Swift source code. That’s what Apple uses to generate their pages, using https://www.swift.org/documentation/docc/.
How to reliably HTML to MD for any page on the internet?
I remember struggling with this in the past
How hard would it be to build an MCP that's basically a proxy for web search except it always tries to build the markdown version of the web pages instead of passing HTML?
Basically Sosumi.ai but instead of working on only for Apple docs it works for any web page (including every doc on the internet)
show comments
saagarjha
Is it possible to download an archive of the data so I can run searches against it locally (without AI)?
AzzyHN
This is really cool, but also totally something you'd think existing AI agents should have zero issues with. _Especially_ if they're supposed to be for coding, I'd expect loads of documentation to be baked-in, so to speak
jcoletti
This is awesome and timely for me...going to give it a whirl. Thanks for building. Also, there should totally be an easter egg where clicking something somewhere plays the sound!
show comments
smerrill25
As someone who is currently building my first iOS app, I am extremely happy to have this. This will be much nicer doing my animation documentation.
novok
Hope this make apple's Xcode team realize they should do this, especially with all the recent AI integration.
I think it's safe to assume most big players have browser rendering enabled (I hope so). imo AI is struggling with a lot of languages that are not as popular as javascript, mostly because it's more niche and you don't get a lot of good examples on the web.
show comments
tempodox
An “AI” that makes text “AI”-readable. How does that make any sense?
ChrisMarshallNY
I don't even bother trying to render docc catalogs into JS. It's a royal pain that breaks easily.
If GitHub could support .docc files, that would be great. Otherwise, I still use Jazzy Docs.
show comments
fabiensanglard
It is for the same reasons LLM are struggling to produce something that compile in Rust? I was under the impression that most of Rust documentation was plain HTML.
thomask1995
Very interesting. You have any before and after examples?
Curious how it handles some of the concurrency stuff. Actors, async/await etc..
show comments
zach_moore
I’m building a swift app now and will most definitely give this a try
the_arun
Just wondering - can't AI read HTML? If so how are we training our models?
show comments
jordanmorgan10
Another awesome project that does this for Apple's docs: https://llm.codes/
Also, Apple has started shipping docs like this, too. They are a bit hidden but you can find them here:
Do you have a public repo? Would love to see how it's working.
show comments
awaseem
Can't wait to use this. Its awesome!
show comments
hirvi74
> "Ever notice Claude struggling to write Swift code?"
Yes, that is why I quit using Claude and swapped to ChatGPT about a year ago. I've had substantially less issues with GPT.
show comments
rtk0
Love the name.
croes
Wasn’t one of the benefits of AI that we don’t need special documents for AI to understand the data?
show comments
WA
sosumi.md seems to be a better fit domain-wise, no?
miki123211
Just saying, sites like these are also pretty great for accessibility, screen reader users in particular.
I think this one would be slightly better if it rendered that Markdown as simple HTML if accessed through a real browser, but I can imagine even this version being pretty useful.
I think it could also make the "Small web" crowd pretty happy too.
hamza_q_
This is awesome; great work.
amelius
Aha, another developer doing Apple's job.
diimdeep
Could you share what is your motivation behind doing whole domain and web hosting ?
Personally I feel that this whole AI induced problem should even exist in the first place, but even then it is ridiculous, that you have to query some web api to solve this problem, why not just publish parsed and converted to .md set of local files and be done with it.
For those wondering about the name, it has a fun story behind it: https://en.wikipedia.org/wiki/Sosumi
"AI-readable Markdown" — can't we just say "Markdown"? I'm serious about this, why are we focussing on making things accessible to AI when they should just be machine-readable and accessible to human beings in the first place? No need to taint this by bringing AI into it.
Nice! Do you think it could be adapted to other docs sites?
I made a small clone of the tutorials section (https://clone-swiftui-tutorial.vercel.app/) where the content is already Markdown (and use codehike to turn the markdown into a rich UI). This made me realize that codehike is AI-friendly, in the sense that even for non-linear UIs the original content is still AI-readable Markdown.
Great promise; sometimes need to reference docs to build context.
I looked at the examples you posted and did a quick glance. For example
'''init?(exactly: Float80)'''
the tool converted it to
'''- [initexactly-63925](/documentation/Swift/Double/init(exactly:)-63925)'''
To achieve its goal I would be worried that it dropped the verbatim function signature. Claude still figured it out, but for more obscure stuff that could be an issue.
Hm, I would have extracted the markdown from the Swift source code. That’s what Apple uses to generate their pages, using https://www.swift.org/documentation/docc/.
For example, AFAIK, https://github.com/swiftlang/swift/blob/main/stdlib/public/c... is used to generate https://developer.apple.com/documentation/swift/array.
How to reliably HTML to MD for any page on the internet? I remember struggling with this in the past
How hard would it be to build an MCP that's basically a proxy for web search except it always tries to build the markdown version of the web pages instead of passing HTML?
Basically Sosumi.ai but instead of working on only for Apple docs it works for any web page (including every doc on the internet)
Is it possible to download an archive of the data so I can run searches against it locally (without AI)?
This is really cool, but also totally something you'd think existing AI agents should have zero issues with. _Especially_ if they're supposed to be for coding, I'd expect loads of documentation to be baked-in, so to speak
This is awesome and timely for me...going to give it a whirl. Thanks for building. Also, there should totally be an easter egg where clicking something somewhere plays the sound!
As someone who is currently building my first iOS app, I am extremely happy to have this. This will be much nicer doing my animation documentation.
Hope this make apple's Xcode team realize they should do this, especially with all the recent AI integration.
Reminds me a bit of https://www.felixcloutier.com/x86/ - turning thousands of pages of Intel PDF into more semantic documentation.
I think it's safe to assume most big players have browser rendering enabled (I hope so). imo AI is struggling with a lot of languages that are not as popular as javascript, mostly because it's more niche and you don't get a lot of good examples on the web.
An “AI” that makes text “AI”-readable. How does that make any sense?
I don't even bother trying to render docc catalogs into JS. It's a royal pain that breaks easily.
If GitHub could support .docc files, that would be great. Otherwise, I still use Jazzy Docs.
It is for the same reasons LLM are struggling to produce something that compile in Rust? I was under the impression that most of Rust documentation was plain HTML.
Very interesting. You have any before and after examples?
Curious how it handles some of the concurrency stuff. Actors, async/await etc..
I’m building a swift app now and will most definitely give this a try
Just wondering - can't AI read HTML? If so how are we training our models?
Another awesome project that does this for Apple's docs: https://llm.codes/
Also, Apple has started shipping docs like this, too. They are a bit hidden but you can find them here:
/Applications/Xcode-beta.app/Contents/PlugIns/IDEIntelligenceChat.framework/Versions/A/Resources/AdditionalDocumentation
Do you have a public repo? Would love to see how it's working.
Can't wait to use this. Its awesome!
> "Ever notice Claude struggling to write Swift code?"
Yes, that is why I quit using Claude and swapped to ChatGPT about a year ago. I've had substantially less issues with GPT.
Love the name.
Wasn’t one of the benefits of AI that we don’t need special documents for AI to understand the data?
sosumi.md seems to be a better fit domain-wise, no?
Just saying, sites like these are also pretty great for accessibility, screen reader users in particular.
I think this one would be slightly better if it rendered that Markdown as simple HTML if accessed through a real browser, but I can imagine even this version being pretty useful.
I think it could also make the "Small web" crowd pretty happy too.
This is awesome; great work.
Aha, another developer doing Apple's job.
Could you share what is your motivation behind doing whole domain and web hosting ?
Personally I feel that this whole AI induced problem should even exist in the first place, but even then it is ridiculous, that you have to query some web api to solve this problem, why not just publish parsed and converted to .md set of local files and be done with it.