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 short article.
Could you introduce yourself? Where are you from?
👋🏻 Hi! I'm Miguel Piedrafita, a 16-year-old from Spain.
What’s your story?
I've always been attracted to computers, so when I was introduced to HTML by a teacher at my school, I knew that was what I wanted to do. I started to learn on my own, HTML & CSS first, then Javascript, PHP, etc.
After a few 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 repository 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 an 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 to be able to render documentation without cloning it in my server.
After I got a demo working, I decided to keep working on it, and built a few extensions on top of my markdown parser to allow to embed videos, codepens 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 to do 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 paying $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 want to share about you 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.
Top comments (0)