Create API Documentation Using Squarespace

There are a lot of API documentation tools out there, but none of them seemed to exactly fit the bill, so I decided to just write my company’s API documentation using Squarespace. Squarespace’s name is kind of funny because it’s often like trying to fit a square space in a round hole. Nevertheless, Squarespace has beautiful designs and a no-maintenance hosting platform. In addition, using a content management system (CMS) means that documentation changes are effortless and don’t require any deployments.

For all you Squarespace lovers out there, this post describes how to create API documentation using Squarespace. To see an example of the finished product, see this REST API Boilerplate reference that I created.

Note that I used highlight.js to automatically format the curl and JSON examples; however, doing so requires Squarespace’s Code Injection feature, which in turn requires at least Squarespace’s Business Plan (currently $18/mo). If you just need to format curl and JSON examples, you can do so with just a bit of custom CSS.

Create a New Site

Go to https://account.squarespace.com/

Pick a Template

The color scheme and font family of the “Ready” template seem to work well for API documentation.

Enable Syntax Highlighting

Use the following Code Injection. You can customize the syntax highlighting via the “api-example-code” CSS class (see below).

Thanks to Stephen Gurnett for his post about how to get syntax highlighting to work in Squarespace.

Add Custom CSS

Add the following custom CSS to jazz up your documentation.

Create a New Page

Page Setup

Use the blank layout.

Add a Title

Add a Section

Use the following code so as to add a bookmark to this section.

<h2 id="section-xyz">SectionXYZ</h2>

Add a Subsection

Use the following code so as to add a bookmark to this subsection.

<div id="subsection-abc" class="api-h3-section">
<h3>SubsectionABC</h3>
</div>

Add a Subsection Description

Create an Example Block in 2-Column Format

See the following code used in this example.

Describe the Arguments

See the following code used in this example.

Describe the Response

See the following code used in this example.

Set the Home Page & URL Slug

Add a Navigation Folder

Folder names should match the section header names, but it’s not required.

Add a Navigation Link

The link path must match the name of the URL Slug (see “URL Slug” — e.g. “/api-doc”).

The bookmark (#) must match the “id” field used in the subsection (see “Add a Subsection”).

Final Note

If you need some examples of verbose and complete API references, my favorites are Coinbase and Stripe.

Passionate about Software Engineering, Finance, and the technology tools that help us in those endeavors.