I was contacted by GitHub last year to do an interview about UnMarkDocs and how I used their API to build it. They didn't end up publishing it, so I thought it'd make good material for a 200wad. Who knows, maybe I'll end up publishing it in my blog...
Could you introduce yourself? Where are you from?
👋🏻 Hi! I'm Miguel Piedrafita, a 16-year-old from Spain.
What’s your story?
After some testing projects, I built my first real thing, an invite system for GitHub organizations, called OrgManager. I kept experimenting with more little projects using the GitHub API. UnMarkDocs and Snaptier are some of the results of those experiments.
Could you introduce UnMarkDocs? What does it do?
UnMarkDocs converts raw Markdown files stored in a GitHub repo into beautiful documentation pages. It also provides some extensions so you can use Markdown to add alerts, call-to-actions, embed videos, codepens, gists, etc. Finally, it makes sure the changes in the repository are synced with your page.
What’s the story behind UnMarkDocs? Why did you build it?
UnMarkDocs started as two different projects. I was learning CSS, and I made a UI kit for documentation pages. I wanted to use it for my open-source projects' documentation, so I tried to connect it with the GitHub API. Using the power of the Contents API, I was able to render the documentation without cloning it in my server.
After I got a demo working, I decided to keep working on it. I built a few extensions on top of the markdown parser to allow to embeds and other things I thought could be useful for documentation pages.
What has been your favorite feature of the GitHub API?
Definitely the Contents API. It allows doing so many things with repositories hosted on GitHub without having to actually store the files in your server, which is very helpful for people that can afford to pay $500 each month for servers. This endpoint powers most of the apps that I've built with the GitHub API.
What was the most challenging thing about building UnMarkDocs using the API?
Making the changes on the repository reflect instantly on the documentation pages. I wanted to always have the latest version of the content, but I also wanted pages to load fast. My solution was to cache the contents and clear the cache on push using webhooks and a GitHub App.
Did you work with the new v4 GraphQL API? Why or why not?
I used the GraphQL API to auto-generate navigation by getting the file tree. It saved me from doing multiple calls to the GitHub API in every page render and also allowed me to get a deeper tree by using fragments.
Initially, I was using a separate OAuth app for this, but when the GitHub team added GraphQL to GitHub Apps (thanks!), I integrated it on the main app.
Anything else you want to share about your experience? Any stories or lessons learned through building UnMarkDocs?
I learned a lot while building UnMarkDocs. In the tech side, I learned about extending markdown, design, more CSS, responsiveness... but I also learned a lot about marketing, validation, and how to build a SaaS in general from the entrepreneurial side.