How to Use Notion for API Documentation (w/ Free Template)

published on 09 April 2022
notion-api-01-bza46

Ask any developer and they’ll agree: Notion is awesome. It truly is the all-in-one workspace for your company.

At my prior companies we’ve used notion for literally everything, including:

  • Internal Wiki
  • Help-Guides for customers
  • API Documentation
  • HR Wiki
  • Document storage
  • Engineering Wiki
  • Product Roadmap
  • Sales Playbook
  • Basic CRM
  • […]

You get the point. It’s a versatile tool. But, one of my favorite use-cases for Notion is as public API documentation.

Want an example?

There’s many great examples of this, including this API documentation by beestat, and this great example documentation page. Here’s what that looks like:

[from beestat.io docs]
[from beestat.io docs]

As you can see there’s a top navigation section. Then, through smart utilization of sub-pages, lists, and code blocks they’ve created their entire product documentation inside Notion.

How can I replicate this for my documentation?

Step 1: Duplicate the template

  1. Create a Notion account.
  2. Copy my pre-made Template by clicking the button below (or going here) then clicking “duplicate” in the top-right corner.

Step 2: Customize

The template can be split into 3 parts: The navigation, the documentation, the references.

The navigation section will be automatically updated as you add new /h1, /h2 and /h3 sections to your page. This is super convenient and just another awesome feature of Notion.

Secondly, you have the meat of the content: the documentation. Feel free to copy and paste the examples already there and organize them however you want.

Finally, at the bottom of the page is a resources section. This is where you can add extra pages and then reference them throughout the docs by doing @pagename. This is really convenient because now you can reference the same page multiple times and it gives an easy ‘back’ button on those subpages as-well.

Step 3: Deploy

Deployment can be done a variety of ways. First, the simplest way to deploy these docs is through Notion’s page publishing.

This can be done by clicking the share button in the top right corner and toggling the “Share to web” button to true. This works fine, but it means you end up with a domain that looks like this:

https://www.notion.so/API-Documentation-by-pwego-com-5aa91838eac744248f1e2b9158425964

What if we wanted to host on a custom domain? Ex.

api.yoursite.com

Well, there’s an awesome tool I can recommend called Engine.so that does this and more. Engine lets you host your Notion pages externally at a custom domain, but also gives a plethora of features specifically for hosting knowledge bases.

When you host with Engine.so, it will look something like this:

As you can see, Engine.so provides a handy side navigation. It also gives you custom branding to your page, a full-text search widget, and the ability to embed analytics, support, and email capture to your page.

This means you can write in Notion, press publish, and the rest is handled for you. Pretty cool.

Anyways, I hope this helped. If you have any questions, feel free to reach out on twitter @spencerpauly.