Jekyll API site

Prerequisites

Assume that you have Jekyll, Git client, and Visual Studio Code editor installed on your computer. If not, read the Jekyll article first.

To check that you have Jekyll installed:

1. Open Command Prompt.

   

2. Enter jekyll -v and press Enter.

   

To check that you have Git and VSCode installed:

1. In the Command Prompt, enter git --version.

   

2. Check that you have Visual Studio Code installed.

   

Download the theme

To download the Jekyll theme for your API documentation site:

1. Go to the theme GitHub repository.

2. Select Code.

3. Select Download ZIP.

   

4. Save the zipped project folder to your computer.

5. Unzip the folder.

Launch the site locally

Before publishing this site online, let’s check how the site runs locally on your computer.

Install Bundler

1. Browse to the location where you unzipped the project folder.

2. Delete the existing Gemfile and Gemfile.lock files.

   

3. In the file explorer, copy the path to the project folder.

   In my case, it’s c:\Users\ivanc\aviator-jekyll-template-master\

   

4. In the Command Prompt, change the directory to your project folder path. Press Enter.

   cd c:\Users\ivanc\aviator-jekyll-template-master\

5. Enter gem install bundler and press Enter.

   

6. Enter the following commands.

   bundle init
   
   bundle install
   

   

   These commands created new Gemfile files in your project folder.

Bundle update

1. Open the Gemfile with Notepad.

   

2. Delete everything in this file.

3. Enter the following data and save the file.

   source 'https://rubygems.org'
   
   gem 'jekyll', '3.7.2'
   gem 'tzinfo-data'
   
   group :jekyll_plugins do
    gem 'jekyll-seo-tag', '2.4.0'
    gem 'jekyll-sitemap', '1.2.0'
   end
   

   

4. Enter bundle update and press Enter.

   

Build the site

To build your Jekyll site locally:

1. Enter bundle exec jekyll serve and press Enter.

   

2. Copy the server address:

   http://127.0.0.1:4000

3. Paste it in your browser and you should see your site served locally.

   

Publish the site online

When you finish editing the site locally, it’s time to publish it online for everybody to see. For this example, I will use the Vercel platform to deploy and host your site. But first you need to upload your project folder to GitHub.

Publish to GitHub

To upload your project folder to GitHub:

1. In VSCode, open the project folder.

2. Select the Source Control icon.

   

3. Select Publish to GitHub.

4. Select Publish to GitHub public repository.

   

   When the project folder has been uploaded to the GitHub repository, you will see this success message.

   

5. Select Open in GitHub to view your project folder uploaded and synced to the GitHub repository.

   

Deploy to Vercel

To publish your site online, you need to deploy it to Vercel.

1. Go to Vercel.

2. Select Continue with GitHub.

   

3. Select Import Project.

   

4. Select Continue to import your project from GitHub.

   

5. Provide the link to your GitHub repository and select Continue:

   https://github.com/ivancheban/aviator-jekyll-template-master

   

6. Enter the project name: for example, aviator-jekyll-template-master. Select Deploy.

   Note

   This name will be used in the link to your site. You can always change the site name in the Vercel settings in Domains.

   

   Note

   The project deploy takes several minutes. Be patient.

   When the deploy finishes you will see this nice success screen.

   

7. Select Visit to go to your API documentation site available online.

   You should see your site similar to this:

   https://aviator-jekyll-template-master.vercel.app/