Building a Markdown-Supported Blogging Platform with Jamstack

Why Markdown is the Ideal Choice for Your Jamstack Blog

Among the various approaches to web development, Jamstack stands out as a modern architecture that offers enhanced performance, security, and scalability.

This article will explore building a blogging platform that supports Markdown.

It will use a Jamstack approach with Eleventy or Hugo for static site generation, Netlify CMS for content management, and Netlify for hosting.

The platform will include features like blog posts organized by categories/tags, a simple commenting system, and RSS feed generation.

Why Choose Markdown for Your Blog?

Thanks to its simplicity and flexibility, markdown has become the go-to markup language for writers and developers alike.

It allows content creators to focus on writing without worrying about complex formatting.

With Markdown, you can write in a plain text format, using simple syntax to define headers, lists, links, and other elements.

This plain text can be converted into HTML, making it ideal for blogging platforms.

Markdown’s popularity in blogging platforms is also driven by its compatibility with version control systems like Git, allowing seamless collaboration and content management.

Additionally, Markdown files are lightweight, easy to read, and portable, making them a perfect choice for a static site generator (SSG) like Eleventy or Hugo.

Introduction to Jamstack

Jamstack, an acronym for JavaScript, APIs, and Markup, represents a modern web development architecture designed to make websites faster, more secure, and easier to scale.

Unlike traditional web architectures, which rely on servers to generate content dynamically, Jamstack delivers content via pre-rendered static pages and client-side JavaScript.

This approach decouples the frontend from the backend, enabling developers to build the front end using static site generators (SSGs) like Eleventy or Hugo while relying on APIs for dynamic content.

Why Eleventy or Hugo for Static Site Generation?

Eleventy and Hugo are the most popular SSGs used in Jamstack development.

They both offer unique advantages that make them suitable for a Markdown-supported blogging platform.

• Eleventy is a highly flexible and simple SSG that supports multiple template languages, including Markdown, HTML, and JavaScript. It allows developers to structure their projects however they like, offering complete control over the output. Eleventy is known for its minimalistic approach, making it easy to learn and use.
• Hugo, on the other hand, is known for its speed. Hugo can generate thousands of pages in seconds written in Go, making it one of the fastest SSGs available. It also comes with built-in support for taxonomies, allowing you to easily organize your blog posts by categories and tags. Hugo’s extensive theming and plugin options make it a powerful tool for building feature-rich blogs.

Eleventy and Hugo support Markdown, allowing you to write content in Markdown and automatically convert it to HTML during the build process.

Setting Up Your Blogging Platform

Let’s set up your Markdown-supported blogging platform using Eleventy or Hugo.

Initial Setup with Eleventy

1. Install Node.js: Ensure Node.js is installed on your system, as Eleventy is a Node.js based SSG. You can download it from the official Node.js website.

2. Create a New Eleventy Project: Open your terminal and run the following commands to create a new Eleventy project:

mkdir my-blog
cd my-blog
npm init -y
npm install @11ty/eleventy --save-dev

Configure Eleventy: Create a .eleventy.js configuration file in the root directory of your project.

This file allows you to customize Eleventy’s behavior.

Here’s a basic example:

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("src/assets");
  return {
    dir: {
      input: "src",
      output: "dist"
    }
  };
};

Create Your First Markdown Post: Inside the src directory, create a folder named posts and add a new Markdown file:

---
title: "Hello World"
date: "2024-08-30"
tags: ["introduction"]
---

Welcome to my new blog powered by Eleventy and Markdown!

Build and Serve: Run the following command to build your site and serve it locally:

npx eleventy --serve

Viewing Your Site: Open your browser and go to http://localhost:8080 to view your new blog.

Initial Setup with Hugo

Install Hugo: Download and install Hugo from the official Hugo website.

Create a New Hugo Site: Open your terminal and run the following commands to create a new Hugo site:

hugo new site my-blog
cd my-blog

Add a Theme: Hugo has a vast collection of themes that you can use to customize your blog.

You can browse them on the Hugo Themes website. To add a theme, run:

git init
git submodule add https://github.com/themename/theme-repo.git themes/theme-name

Configure Hugo: Edit the config.toml file in the root directory to configure your site.

Here’s an example:

baseURL = "https://example.com/"
languageCode = "en-us"
title = "My Blog"
theme = "theme-name"

Create Your First Markdown Post: Run the following command to create a new post:

hugo new posts/hello-world.md

Edit the Markdown file generated in the content/posts directory:

---
title: "Hello World"
date: "2024-08-30"
tags: ["introduction"]
---

Welcome to my new blog powered by Hugo and Markdown!

Build and Serve: Run the following command to build your site and serve it locally:

hugo server -D

Viewing Your Site: Open your browser and go to http://localhost:1313 to view your new blog.

Adding Content Management with Netlify CMS

While static site generators like Eleventy and Hugo make it easy to build a blog, managing content directly in Markdown files can be cumbersome for non-technical users.

This is where Netlify CMS comes in.

Netlify CMS is an open-source content management system that allows users to create and manage content through a user-friendly interface, even for static sites.

Integrating Netlify CMS

Add Netlify CMS to Your Project: First, create a new directory called admin in your project’s src or content directory (depending on whether you’re using Eleventy or Hugo).

Inside this directory, create an index.html file with the following content:

<!doctype html>
<html>
<head>
  <title>Content Manager</title>
</head>
<body>
  <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
</body>
</html>

Configure Netlify CMS: Create a config.yml file inside the admin directory.

This file tells Netlify CMS how to manage your content.

Here’s an example configuration:

backend:
  name: git-gateway
  branch: main
media_folder: "src/assets"
public_folder: "/assets"
collections:
  - name: "posts"
    label: "Posts"
    folder: "src/posts"
    create: true
    slug: "{{slug}}"
    fields:
      - { label: "Title", name: "title", widget: "string" }
      - { label: "Publish Date", name: "date", widget: "datetime" }
      - { label: "Tags", name: "tags", widget: "list" }
      - { label: "Body", name: "body", widget: "markdown" }

Deploy to Netlify: Push your project to a Git repository and connect it to Netlify for deployment.

Netlify will automatically detect the presence of Netlify CMS and configure your site to work with it.

Accessing Netlify CMS: Once deployed, you can access the content management interface at https://yoursite.com/admin.

Users can log in and manage blog posts through an intuitive interface.

Organizing Blog Posts with Categories and Tags

Organizing content is crucial for a good user experience.

Eleventy and Hugo offer built-in support for organizing content by categories and tags.

Organizing in Eleventy

In Eleventy, you can use collections to organize posts by categories or tags. You can define collections in your .eleventy.js configuration file:

module.exports = function(eleventyConfig) {
  eleventyConfig.addCollection("posts", function(collection) {
    return collection.getFilteredByGlob("src/posts/*.md");
  });

  eleventyConfig.addCollection("tags", function(collection) {
    return collection.getAll().filter(item => item.data.tags);
  });

 eleventyConfig.addPassthroughCopy("src/assets");

  return {
    dir: {
      input: "src",
      output: "dist"
    }
  };
};

With this configuration, you can create pages listing posts by tag or category.

For example, you can make a page template that iterates over the tags collection and displays posts accordingly.

Organizing in Hugo

Hugo has built-in support for taxonomies like categories and tags.

By default, Hugo recognizes categories and tags as taxonomies, but you can define custom taxonomies in your config.toml:

[taxonomies]
  category = "categories"
  tag = "tags"

When writing a post in Hugo, you can assign categories and tags like this:

---
title: "Hello World"
date: "2024-08-30"
categories: ["Introduction"]
tags: ["hello", "world"]
---

Hugo will automatically generate pages for each category and tag, listing all associated posts.

You can customize the look and feel of these pages by editing the corresponding templates in the layouts directory.

Implementing a Commenting System with Disqus

Engagement is essential to blogging, and allowing readers to comment on posts can significantly enhance interaction.

Disqus is a popular third-party commenting system that can be easily integrated into your Jamstack blog.

Adding Disqus to Eleventy

To add Disqus to an Eleventy blog, include the Disqus embed code in your post layout template. Here’s how you can do it:

Sign Up for Disqus: First, create a Disqus account and register your site. You’ll receive a short name that you’ll use to integrate Disqus with your blog.

Add Disqus Embed Code: In your Eleventy project’s post layout template (e.g., post.njk), add the following code where you want the comments to appear:

<div id="disqus_thread"></div>
<script>
var disqus_config = function () {
    this.page.url = '{{ url }}';
    this.page.identifier = '{{ id }}';
};
(function() {
    var d = document, s = d.createElement('script');
    s.src = 'https://YOUR_DISQUS_SHORTNAME.disqus.com/embed.js';
    s.setAttribute('data-timestamp', +new Date());
    (d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the comments powered by Disqus.</noscript>

Configure URL and Identifier: Replace YOUR_DISQUS_SHORTNAME with your actual Disqus shortname.

Ensure the URL and ID variables correspond to the current post’s URL and identifier.

Adding Disqus to Hugo

Integrating Disqus with Hugo is even simpler, thanks to Hugo’s built-in Disqus support.

Sign Up for Disqus: Like with Eleventy, create a Disqus account and obtain your shortname.

Update Config File: Add your Disqus shortname to the config.toml file:

disqusShortname = "YOUR_DISQUS_SHORTNAME"

Enable Comments in Posts: Ensure that the disqusShortname is correctly set, and Hugo will automatically add the Disqus comment thread to each post.

Hugo will include the Disqus script on each blog post page, letting readers leave comments quickly.

Generating an RSS Feed

RSS feeds are a great way to syndicate your blog content, allowing readers to subscribe and stay updated with your latest posts.

Both Eleventy and Hugo provide straightforward methods to generate RSS feeds.

Generating RSS Feeds in Eleventy

In Eleventy, you can generate an RSS feed using a custom template.

Create an RSS Template: Create a new file in the src directory named rss.xml.

Here’s an example template:

<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
  <channel>
    <title>Your Blog Title</title>
    <link>{{ metadata.url }}</link>
    <description>{{ metadata.description }}</description>
    <language>en-us</language>
    {{ collections.posts | rss | safe }}
  </channel>
</rss>

Configure Eleventy for RSS: Add a filter to generate RSS items in your .eleventy.js configuration file.

eleventyConfig.addFilter("rss", (posts) => {
  return posts.map(post => `
    <item>
      <title>${post.data.title}</title>
      <link>${post.url}</link>
      <description>${post.data.excerpt}</description>
      <pubDate>${post.date.toUTCString()}</pubDate>
    </item>
  `).join("\n");
});

Serve the RSS Feed: Include the rss.xml template in your dir. Use the output directory to ensure it is part of your build output.

Your RSS feed will be available at https://yoursite.com/rss.xml.

Generating RSS Feeds in Hugo

Hugo includes a built-in RSS generator that can be easily enabled in your site’s configuration.

Enable RSS in Config: Add the following to your config.toml file:

[outputs]
home = ["HTML", "RSS"]

Access the RSS Feed: Hugo will automatically generate an RSS feed for your blog, accessed at https://yoursite.com/index.xml.

If you need more control over the output, you can customize Hugo’s default RSS template by creating an rss.xml template in the layouts directory.

Deploying Your Blog with Netlify

After setting up your blog with Eleventy or Hugo and adding features like content management with Netlify CMS, commenting with Disqus, and RSS feed generation, it’s time to deploy your site.

Netlify offers a seamless deployment experience with continuous integration, allowing you to push updates to your site easily.

Steps to Deploy with Netlify

• Push Your Code to Git: Ensure your project is under version control with Git. Push your code to a Git hosting service like GitHub, GitLab, or Bitbucket.
• Connect to Netlify: Connect to your Netlify account and create a new site by connecting your Git repository. Netlify will automatically detect the static site generator you’re using (Eleventy or Hugo) and configure the build settings.
• Configure Build Settings: Customize the build settings in Netlify’s dashboard if necessary. For Eleventy, the default build command is npx eleventy, and for Hugo, it’s hugo.
• Deploy Your Site: Netlify will build and deploy your site automatically once connected. Every time you push changes to your Git repository, Netlify will rebuild and redeploy your site, ensuring it’s always up to date.
• Custom Domain: You can also configure a custom domain for your blog through Netlify’s domain management tools.

Building a Markdown-supported blogging platform using Jamstack technologies like Eleventy or Hugo, Netlify CMS, and Netlify for hosting provides a modern, scalable, and user-friendly solution.

By leveraging the simplicity of Markdown, the power of static site generators, and the flexibility of headless content management systems, you can create a high-performance blog that is easy to maintain and extend.

Features like categories and tags, a commenting system with Disqus, and RSS feed generation enhance the user experience, making your blog more engaging and accessible.

Whether you’re a seasoned developer or just starting with Jamstack, this guide provides a comprehensive overview of setting up and deploying a fully functional blogging platform.

By following these steps, you can build a blog that meets your content needs and offers a fast, secure, and scalable solution for your readers.

Follow me on Medium, LinkedIn, and Facebook.

Please clap my articles if you find them useful, comment below, and subscribe to me on Medium for updates on when I post my latest articles.

Want to help support my future writing endeavors?

You can do any of the above things and/or “Buy me a cup of coffee.”

It would be greatly appreciated!

Last and most important, enjoy your Day!

Regards,

George