So, when I look at that documentation, I see three related concepts but they don't always go together. For example, I can parse a Markdown file, format it, and not do any modification. Someone may want to build up some Markdown from structured data and then print it out, so no parsing needs to be done. I don't think I would have combined those concepts into one article if I were writing that documentation, unless I were putting everything about the library on one page. I'm wondering if that article was basically pulled from the repo's README? I think when I wrote the README, it was basically just a "here's everything, I guess" article (which READMEs tend to be).
The goal of snippets is one block of code is one high-level task. Putting that in one file means that an author or a reader doesn't have to do the extra work to sort a growing wall of text, which starts to get back into one of the problems with sample code projects.
If sharing demo code (code that executes but is not shown) among snippets becomes an issue, a package can define a helper library. If sharing presentation code (the code that is actually shown in the rendered code block) becomes an issue, I think that perhaps indicates a potential need for an API. That is another benefit that I see for shorter example code–it highlights the usability (or lack thereof) of libraries very well, so I expect that the more that folks write snippets, the more informed they will be about the design of their API.
A module can import any of the libraries created in its host package. This was a compromise to allow for some flexibility without having to configure each and every snippet. It's possible that we might want to broaden that to libraries pulled in with dependencies–I think someone brought that up above.
I'm not sure I understand what you mean regarding name collisions. These are basically just executable targets. You still need to import libraries to get their APIs, so if each library has their own foo, you need to use A.foo or B.foo to differentiate, same as any Swift code.
This started out as a formal thing that would create semantic groupings, but I made a change to just allow subdirectories without affecting the outgoing Symbol Graph data. Basically, the extra level of subdirectories is purely for organization, and the limit of depth one allows folks to put snippet-related resources in deeper directories without having to resort to fancy naming.
You know it! 