I've written a lot about documenting APIs, but what if your documentation itself could function as an API? By this I mean, what if you could give developers an endpoint through which they could retrieve different parts of your documentation? This setup would work well for context-sensitive help within an application.
I stumbled across a cool Jekyll plugin called Jekyll Pages API that actually allows you to do this. The plugin creates a JSON file containing your site's pages and posts. From this JSON file, developers can make calls for specific data.
Here's an example. I uploaded a vanilla Jekyll site here: docasapi.
The site has 2 pages. I will get the content from those pages using the following endpoint:
You can see the page content formatted as a JSON file by going to the endpoint:
(BTW, it helps to add the Chrome JSON formatter extension to format the JSON in your browser.)
The Jekyll Pages API creates a pages.json file when you build your site.
Here's a sample page showing how one might call the endpoint to retrieve and append the information on a page: Sample Doc API Call.
Just view the source code on that page for the details. There are four examples. I've copied the code here for convenience:
I won't go into much detail about the code except to point out that I demonstrated 4 ways to get the data. Example 1 uses direct dot notation:
data.entries.body. This is simply how you access the JSON you want. However, since the order of the objects might change, this approach would be hard to manage.
The second example uses jQuery's
each method to iterate through the JSON data looking for a page titled "About". However, this method is a little shaky too since page titles frequently change.
The third example uses jQuery's
each method again to iterate through the JSON data, but this time it looks for a specific url. I think this is the most stable approach.
Finally, developers aren't going to be coding all of this logic in their applications. Most likely the functions will be triggered from click or hover events. That's what the last sample shows.
You don't have to know much about Jekyll to get this sample site running. Here are some simple steps to implement it all. You can also download the project here: apirubytest.
These instructions assume you're on a Mac. (Sorry PC people -- I will update this one day. The instructions may be highly similar anyway.)
which ruby. You should see the version and location listed. If you don't have Ruby, install XCode (it contains a lot of dependencies.)
gem install bundler.
gem install jekyll.
jekyll new testsite.
group :jekyll_plugins do
bundle exec jekyll serve.
You should see an address for a server at
http://127.0.0.1:4000. Preview your Jekyll site there.
/api/v1/pages.json after your server path, and you should see the JSON from your pages.
Jekyll builds the site output inside the _site folder. You will find an api folder in the _site output that contains the JSON data.
Note that links don't quite carry over in the JSON unless you swap in character symbols (such as
< for the angle brackets (
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.