← Posts

My Documentation Sites: How they work

February 19th, 2022 - 2 min read

FYI: I originally posted this on Twitter. If you want to see more like this, follow me over there, I'm @_duncanmcclean.

---

Last year, I unified the way I handled the docs sites for my addons.

They're all handled by a single Laravel app which pulls in the content from each addon's GitHub repo.

I thought it could be interesting to share how it works...

1. Get the content from GitHub: If we don't already have the docs content, it'll go grab it using GitHub's zip download feature.

Then, it'll extract the zip and move the docs into their own folder. The images are also moved around, into the 'public' directory.

Screenshot-2022-02-16-at-22.35.59

2. Next up, we go and get the file from the directory we just copied them to. If the requested file doesn't exist, we throw a 404.

Screenshot-2022-02-16-at-22.47.37

3. Now we have the file contents: it's passed into Commonmark's Markdown converter and piped through some extensions, like Torchlight, a YAML front matter parser and one that handles Markdown tables.

Screenshot-2022-02-16-at-22.48.51

4. Now we have the HTML, it's passed into a Document class, along with some bits of metadata, like the page title & path.

At this point, whatever we returned is sent to the Cache so it's super duper quick for the next user to visit this docs page.

Screenshot-2022-02-16-at-22.59.36

5. Last but not least..

Whenever I push changes to my addon's on GitHub, a webhook is triggered which clears the cloned files & the Laravel cache for the addon that's been updated.

Screenshot-2022-02-16-at-23.01.57

And that's it! Honestly a pretty simple system and I'm pretty happy with it.

You can see it in action over on the Runway docs: https://runway.duncanmcclean.com/

Thanks for reading! If you'd like to see more posts like this, consider sponsoring me! I might even send you some stickers.