As software developers and Linux enthusiasts, we often seek efficient and streamlined ways to share our projects, documentations, and thoughts. Static websites offer a lightweight and secure solution without the overhead of dynamic server-side processing. In this post, we’ll explore how to use Markdown and Jekyll to create a static website, delve into the advantages of this approach, and provide detailed instructions to get you started.
Building a personal website or blog doesn’t have to be a daunting task. With tools like Markdown for content creation and Jekyll for site generation, you can efficiently create and manage a static website. This approach eliminates the need for complex setups involving databases and server-side scripting languages, making your site faster, more secure, and easier to maintain.
In the early days of web development, tools like Microsoft FrontPage and Adobe Dreamweaver were popular. They allowed users to design websites using a graphical interface (What You See Is What You Get - WYSIWYG), which was ideal for beginners. However, the HTML generated by these tools was often bloated and not standards-compliant.
As developers became more proficient, many transitioned to writing raw HTML and CSS to have finer control over their websites. This approach, while offering more flexibility, was time-consuming, especially for larger sites where content updates were frequent.
The desire for dynamic content led to the adoption of content management systems (CMS) like WordPress. WordPress made it easy to create and manage content, but it introduced new challenges:
For many developers, the optimal solution lies in static site generators like Jekyll. They combine the simplicity and performance of static sites with the ease of content management provided by dynamic sites.
Markdown is a lightweight markup language that allows you to write content in a plain text format that is easy to read and write. It converts simple text formatting into valid HTML, making it ideal for writing documentation, blog posts, and any content destined for the web.
Here’s a quick reference to some common Markdown elements:
# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6
*Italic* or _Italic_
**Bold** or __Bold__
***Bold and Italic*** or ___Bold and Italic___
Unordered Lists
- Item 1
- Item 2
- Subitem 2.1
- Subitem 2.2
Ordered Lists
1. First Item
2. Second Item
1. Subitem 2.1
2. Subitem 2.2
[Link Text](https://example.com)
```layout: post
title: "Jekyll: the special sauce that makes this blog tick"
date: 2021-09-25 00:35:14 -0500
background: /img/textedit.jpg
#### Images
```markdown
Inline Code
Use the `code()` function.
Block Code
```language
// Code example
function greet() {
console.log("Hello, World!");
}
```
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Data 1 | Data 2 | Data 3 |
| Data 4 | Data 5 | Data 6 |
Markdown is widely supported and can be used in various environments:
Jekyll is a static site generator written in Ruby. It takes your Markdown files and converts them into a complete static website. Jekyll provides templating, includes, and other features that allow you to build complex sites without server-side processing.
To get started with Jekyll, ensure you have the following installed:
For Debian/Ubuntu-based systems:
sudo apt-get install ruby-full build-essential zlib1g-dev
Add the following to your .bashrc or .zshrc to avoid installing gems as root:
# Install Ruby Gems to ~/gems
export GEM_HOME="$HOME/gems"
export PATH="$HOME/gems/bin:$PATH"
Install Bundler:
gem install bundler
Install Jekyll and Bundler gems:
gem install jekyll bundler
Navigate to the directory where you want to create your site and run:
jekyll new my-awesome-site
This command creates a new directory named my-awesome-site with the default Jekyll structure.
cd my-awesome-site
To build your site and start a local development server, run:
bundle exec jekyll serve
Your site will be accessible at http://localhost:4000.
YEAR-MONTH-DAY-title.MARKUP.Open _config.yml and set your site parameters:
title: My Awesome Site
email: [email protected]
description: >- # this means to treat the following lines as a single string
Welcome to my awesome site built with Jekyll.
baseurl: "" # the subpath of your site, e.g., /blog
url: "https://yourdomain.com" # the base hostname & protocol for your site
Create a new Markdown file in the _posts directory:
cd _posts
touch 2023-10-25-welcome-to-jekyll.md
Add the following content:
---
layout: post
title: "Welcome to Jekyll!"
date: 2023-10-25 12:00:00 +0000
categories: jekyll update
---
You can write content here in **Markdown**.
Here's some code:
```ruby
def print_hello
puts 'Hello, world!'
end
#### Customizing Layouts and Includes
- **Layouts**: Modify files in `_layouts/` to change the structure of your pages.
- **Includes**: Use `_includes/` for snippets like headers, footers, or other reusable elements.
### Step 7: Build the Site
Whenever you make changes, rebuild the site:
```bash
bundle exec jekyll build
This command regenerates the static files in the _site directory.
GitHub Pages supports Jekyll out of the box.
Create a Repository: The repository name should be <your-username>.github.io.
Push Your Site: Commit and push your Jekyll site to this repository.
Access Your Site: Navigate to https://<your-username>.github.io.
Note: GitHub Pages uses a specific version of Jekyll. Ensure compatibility by referencing the GitHub Pages documentation.
Similarly, GitLab Pages can host your Jekyll site.
Create a New Project: Name it appropriately.
Add a .gitlab-ci.yml: This file defines the CI/CD pipeline to build and deploy your site.
image: ruby:2.7
before_script:
- gem install jekyll bundler
stages:
- build
variables:
JEKYLL_ENV: production
cache:
paths:
- vendor/
build:
stage: build
script:
- bundle install --path vendor
- bundle exec jekyll build -d public
artifacts:
paths:
- public
Push Your Site: Commit and push your site files along with the .gitlab-ci.yml.
Access Your Site: GitLab provides a URL where your site is hosted.
Services like Netlify and Vercel offer free plans for deploying static sites. They integrate with Git repositories and automatically build and deploy your site when you push changes.
You can host your static site on any server or even on object storage services like Amazon S3.
Create an S3 Bucket: Enable static website hosting.
Upload Your Site: Copy the contents of _site to your S3 bucket.
Configure CloudFront: Set up a CDN distribution for better performance and HTTPS support.
Building a static website with Markdown and Jekyll offers a streamlined and efficient way to maintain an online presence. It’s particularly well-suited for developers and Linux users who appreciate simplicity, performance, and security.
By leveraging Markdown’s ease of use and Jekyll’s powerful static site generation, you can create a website that is both easy to manage and delightful for your visitors.
This post is orriginally from a presentation that I gave to the Central Iowa Linux User’s Group and the video can be seen here
About the Author
As a seasoned software developer and the president of the Central Iowa Linux User Group (CIALUG), I have been navigating the evolving landscape of web development since the 90s. From the early days of WYSIWYG editors to embracing static site generators, my journey reflects a pursuit of efficient and effective solutions that empower developers to focus on what matters most: creating and sharing valuable content.