Using DocC to create documentation for standalone markdown files

Hi! My apologies in advance if this is indeed documented somewhere, but I had to struggle a bit to find out how to get docc to render standalone markdown content. Maybe this'll be helpful for other folks like me in the future, and also by posting it here someone can correct me if I'm missing something obvious.

  1. Create an empty folder with a prefix .docc.

    mkdir Documentation.docc
    
  2. Add the following minimal Markdown.

    # Hello
    
    @Metadata {
        @TechnologyRoot
    }
    
    World
    
  3. Preview using docc.

    pbpaste > Documentation.docc/Hello.md
    xcrun docc preview Documentation.docc
    

I also wrote down notes from my first impressions with DocC - these might be useful to the DocC team members to see how the DocC documentation looks for newcomers. There's a bit of jesting in the post, but it's only for humor - I fully realize that rendering standalone markdown is not the primary use case for docc, so it is understandable that the workflow for this is not fully documented.

I also found a (rather harmless) crash when DocC tries to parse an Info.plist without a bundle id - more info about that is also in the post.

The rendered documentation indeed does look beautiful, so thank you all for your work on docc.

2 Likes

Hi @mnvr, glad to hear you were able to get things working.

As far as making things easier, you might find this post by @sofiaromorales interesting, which pitches an idea for making a new DocC command that makes it simple to get started with template content.

2 Likes

Hi @mnvr! I'm implementing an 'init' command in DocC, and the template is very similar to the one you posted. I'm hoping it will make the experience easier :smile:

2 Likes

Yes, a docc init will be nice indeed!

Thank you both for continuously improving the docc experience :blush:

2 Likes