The Nix language is a specialized, purely functional programming language. It’s used by the Nix package manager to build packages and the NixOS operating system for declarative system configuration and software packaging.

Unlike traditional Linux distributions, NixOS utilizes the Nix programming language to describe the entire system, including packages, services, users, networking, and even the bootloader – all of which are defined through a declarative configuration. This approach enables NixOS to generate complete system profiles, allowing for reproducible deployments, atomic upgrades, and easier system rollbacks.

In simpler terms, in NixOS, you can configure your programs, services, and users, and install new system-wide packages or applications directly within the configuration.nix file – which you can then share directly with others.

Also, if anything goes wrong with your current NixOS generation during the system build time, you can roll back to a previous NixOS generation (after switching to a new generation – more on this below).

In this tutorial, I’ll explain in detail what NixOS is, how it works, its benefits, and how to set it up on your machine or laptop in a beginner-friendly way.

Table of Contents:

1. Prerequisites

2. What is a Declarative Configuration?

   • Why is the Declarative Approach (Declarative Configuration) used in NixOS?

   • What Are Reproducible Systems?

3. How Does NixOS Work?

4. What Are the Benefits of Using NixOS?

5. When Would NixOS Not Be the Best Choice?

6. How to Set Up NixOS and the Nix Package Manager on Your Laptop

7. How to Install a Package in NixOS?

8. FAQ

9. Conclusion

Prerequisites

To work with NixOS and the Nix package manager, there are no specific prerequisites if you have at least a couple years of experience with Ubuntu, Debian, or any other distribution. Having some basic knowledge of the Nix language is a plus.

What is a Declarative Configuration?

In the declarative approach, we use a file (such as a YAML, JSON, or Nix) to describe the configuration for hardware and software components, such as systems, networking, users, boot loader, services (like with systems), and more, in one file.

NixOS uses the configuration.nix file for its declarative configuration. By default, the configuration.nix file looks like this:

# /etc/nixos/configuration.nix

{ config, pkgs, ... }:
{

  imports = [
      ./hardware-configuration.nix
   ];

  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  networking.hostName = "nixos"; # Define your hostname.

  # Enable networking
  networking.networkmanager.enable = true;

  # Set your time zone.
  time.timeZone = "Asia/Kolkata";

  # Select internationalisation properties.
  i18n.defaultLocale = "en_IN";

  i18n.extraLocaleSettings = {
    LC_ADDRESS = "en_IN";
    LC_IDENTIFICATION = "en_IN";
    LC_MEASUREMENT = "en_IN";
    LC_MONETARY = "en_IN";
    LC_NAME = "en_IN";
    LC_NUMERIC = "en_IN";
    LC_PAPER = "en_IN";
    LC_TELEPHONE = "en_IN";
    LC_TIME = "en_IN";
  };

  # Enable the X11 windowing system.
  services.xserver.enable = true;

  # Enable the GNOME Desktop Environment.
  services.xserver.displayManager.gdm.enable = true;
  services.xserver.desktopManager.gnome.enable = true;

  # remove preinstall or  unused package in gnome
  environment.gnome.excludePackages = with pkgs; [ gnome-tour gnome.gnome-music nixos-render-docs  ];
  services.xserver.excludePackages = with  pkgs; [ xterm ];

  # Configure keymap in X11
  services.xserver.xkb = {
    layout = "us";
    variant = "";
  };

  # Enable sound with pipewire.
  sound.enable = true;
  hardware.pulseaudio.enable = false;
  security.rtkit.enable = true;
  services.pipewire = {
    enable = true;
    alsa.enable = true;
    alsa.support32Bit = true;
    pulse.enable = true;
  };

  # Define a user account. Don't forget to set a password with ‘passwd’.
  users.users.officialrajdeepsingh = {
    isNormalUser = true;
    description = "officialrajdeepsingh";
    extraGroups = [ "networkmanager" "wheel" "docker" ];
    packages = with pkgs; [
      google-chrome
    ];
  };

  # Enable automatic login for the user.
  services.xserver.displayManager.autoLogin.enable = true;
  services.xserver.displayManager.autoLogin.user = "officialrajdeepsingh";

  # Workaround for GNOME autologin: https://github.com/NixOS/nixpkgs/issues/103746#issuecomment-945091229
  systemd.services."getty@tty1".enable = false;
  systemd.services."autovt@tty1".enable = false;


  services.openssh = {
      enable = true;
      settings = {
        PasswordAuthentication = true;
      };
  };
  system.stateVersion = "23.05"; # Did you read the comment?
}

You can edit the configuration.nix file to easily enable NGINX and Git using NixOS options. NixOS options let you choose whether to turn features on or off and configure how they should work.

# /etc/nixos/configuration.nix

services.nginx.enable = true;
programs.git.enable = true;

....

Every time you modify the configuration.nix file to apply changes to NixOS, you’ll need to build your NixOS using the following command:

sudo nixos-rebuild switch

The nixos-rebuild command generates a new NixOS generation based on your configuration file. This generation is a complete, immutable snapshot of your system's configuration (packages, services, settings) that’s created every time you run that nixos-rebuild command.

The switch flag helps to build and activate the new generation at the same time, and make it the default boot in NixOS.

After a system update, if the new generation isn’t desirable, you can roll back or switch to a previous generation using the nixos-rebuild switch --rollback command. For example, if I’m currently on generation 22, which is the default boot, and I don't like this generation, I can use the rollback flag to switch back to generation 21 in NixOS.

The NixOS rollback feature helps you test new functions and features to see if they work properly when you install new applications or programs on NixOS.

Why is the Declarative Approach (Declarative Configuration) used in NixOS?

The Declarative Approach is particularly useful because it allows you to share your NixOS configuration file with other developers using GitHub and GitLab. By using the configuration.nix file, other developers can build the same system or machine (making it reproducible).

This approach also helps you manage configurations because all your settings are in one place, making it easy to adjust them at any time.

What Are Reproducible Systems?

This concept of reproducibility is important. In NixOS, we can achieve reproducibility using the configuration.nix file. For example, when two developers use the same NixOS configuration file on their machines, they can achieve highly reproducible and consistent system setups.

This is one feature that makes NixOS so useful for developers, teams, CI/CD, servers, and DevOps. With NixOS, you can avoid the common issue of "it doesn't work on my machine."

How Does NixOS Work?

NixOS works differently compared to traditional Linux distributions. In traditional Linux distros, such as Ubuntu and Debian, you can use the apt command to install a new application or program in your distro, like this:

sudo apt install git # Install git package

sudo apt install nodejs # Install node.js package

sudo apt install npm  # Install NPM package

But as we discussed above, NixOS uses a declarative configuration approach that’s immutable, reproducible, and portable.

This means that you can’t install any packages or programs like Git, Chrome, Firefox, Node, Deno, Bun, and so on using the apt, dkpg, or pacman commands (as NixOS uses its own package manager, Nix).

Instead, you edit the configuration.nix file and mention your package and program, such as Node.js, NGINX, or Git in the file and rebuild your NixOS using the nixos-rebuild command.

# /etc/nixos/configuration.nix

services.nginx.enable = true;
programs.git.enable = true;

environment.systemPackages = [
  pkgs.nodejs_24
];

Again, this creates a new generation every time you modify the NixOS configuration and run the nixos-rebuild command in your system.

To understand in more detail how NixOS works, check out this more in-depth tutorial.

What Are the Benefits of Using NixOS?

There are many benefits to using NixOS over a traditional distro, some of which I’ve already mentioned. Let’s summarize them here:

1. Declarative configuration: All settings for your system, including programs, applications, and services, are written in a single configuration file rather than being installed manually.

2. Instant rollbacks: There's no need to worry about breaking your system. If something goes wrong during an update, you can easily revert to the previous version.

3. Safe updates: Updates either complete successfully or don’t apply at all, ensuring your system never ends up in a half-broken state.

4. Reproducible systems: With the same configuration, you can recreate the same system every time, eliminating issues like "it doesn’t work on my machine."

5. No dependency conflicts: Multiple versions of applications can coexist without issues, allowing different programs such as Node.js and Python to operate together seamlessly.

6. Extensive package ecosystem: The Nix Packages collection comprises thousands of up-to-date packages maintained by the NixOS community.

7. Setting up a new machine: Copy your configuration file, rebuild the system, and complete the setup in just a few minutes, whether for a laptop or a server.

8. Immutable system: The design of an immutable system keeps core system paths unchanged. This prevents accidental alterations and enhances reliability, as core components become read-only and cannot be modified after the initial build.

When Would NixOS Not Be the Best Choice?

There are various situations where NixOS may not be the best choice for you. Here are some of the main issues:

1. NixOS has a steep learning curve, particularly for beginner and intermediate developers.

2. It doesn’t offer a simple one-click installation solution for applications and programs on your machine or laptop.

3. You can’t install system-wide applications or programs without editing the NixOS configuration files and rebuilding the system.

4. NixOS lacks a larger community and readily available tutorials compared to Ubuntu, and its documentation is not very beginner-friendly – so you may need to rely on your own resources.

How to Set Up NixOS and the Nix Package Manager on Your Laptop

Now we’re ready to dive in and set up NixOS. But what you need to install depends on your operating system:

• On macOS or Windows, you’ll install Nix, the package manager. This lets you use Nix to install and manage software on your existing operating system. You don’t install NixOS itself on macOS or Windows.

• On Linux, installing NixOS means installing a new OS (it’s like installing Ubuntu or Debian).

Because NixOS is a full operating system, you’ll need to install it on a fresh machine or partition, which will typically erase existing data during installation unless you set up dual-booting.

And remember, while NixOS is a Linux distribution, it works differently (than Ubuntu or Debian, for example) because the entire system is configured declaratively using Nix.

Install Nix Package Manager

The following command helps you to install the Nix language and the Nix Package Manager on macOS and Windows (via WSL).

# Windows: Multi-user installation (recommended)
sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon

# Windows: Single-user installation
sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --no-daemon

# MacOS:
sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install)

If you’re a newcomer, before running the command I recommend watching this tutorial on YouTube and checking out the official documentation.

Install NixOS

You can install the NixOS distro with a Linux command. Before proceeding, make sure you meet the following requirements:

• A USB drive (8 GB or more)

• A second computer (to create the USB)

• A backup of your data (installation can erase the disk)

• An internet connection (Wi-Fi or Ethernet)

There are multiple steps for installing NixOS on your machine or laptop. You can check out the following tutorial, which describes in detail how you can install NixOS on your machine very easily.

How to Install a Package in NixOS

NixOS has a large registry of active packages, with 120,000 packages available. Every package you install from the stable channel is built reproducibly and reviewed by the Nix community, so you shouldn’t encounter any issues.

Installing a new package on NixOS using the Nix Package Manager is quite simple. First, visit the NixOS Packages Search site.

Then just search for the package that you’re looking for. In our case, we’ll search for Neovim – and then just type the package name in the search input and hit enter.

Copy the resulting code it shows, and paste it into your configuration.nix file:

# /etc/nixos/configuration.nix

environment.systemPackages = [
  pkgs.neovim # add inside file.
];

Then rebuild your NixOS using the sudo nixos-rebuild switch command. Remember that you’ll need to do this whenever you make changes to the configuration.nix file.

Demo (How to Install Neovim in NixOS)

FAQ

Is NixOS only for advanced users?

No, NixOS can be a great fit for anyone. Due to its steeper learning curve, beginners may struggle at first – but once you understand it, I bet you’ll love it.

Why is the Nix language so weird?

Nix is purely functional and is designed for reproducible builds. It’s not a general-purpose language and is rather a configuration language. You’ll only need 10–15% of the language for daily use.

How is NixOS different from Ubuntu / Arch?

Let’s compare some important NixOS features with other distros:

Can I use NixOS for development?

Yes, NixOS is an excellent distro for:

• Frontend development (Node, Bun, Deno)

• Backend development (Go, Rust, Python)

• Consistent development environments across machines

• CI/CD reproducibility

Is NixOS good for daily use?

Yes – NixOS has an initial learning phase that can be difficult, but once you get past it, you can use NixOS on your work laptops, servers, home PCs, and development machines.

Should I learn NixOS as a beginner developer?

To be honest, if you want quick results, NixOS may not be for you. But if you're aiming for long-term mastery, you will definitely like NixOS.

Does NixOS work on macOS and Windows?

Yes, you can use Nix and the Nix Package Manager on macOS and Windows, and they work well. You can install and package software using the Nix configuration file as mentioned in this tutorial.

Conclusion

I think that NixOS is the best Linux distro – but it’s not super beginner-friendly. Still, I prefer it because it’s a powerful and reliable distro that’s designed for users who value control, reproducibility, and safety.

Managing the entire system through declarative configuration enables consistent setups, safe upgrades, and easy rollbacks. This makes it especially suitable for developers, DevOps engineers, and infrastructure-focused teams.

Just keep in mind that NixOS is not for everyone. Its learning curve and configuration-driven workflow can be steep for beginners, casual users, or those who want quick, click-and-install convenience. So check it out and decide if it’s right for you and your team.

To Learn more beginner tutorials on NixOS, check out the NixOS publication on Medium.

• What is Declarative Configuration in NixOS? Understanding Declarative vs Imperative Approaches

• Understand the difference between Home Manager vs Nix Flake in NixOS?

• Why did I choose NixOS, and what are the advantages and disadvantages of using NixOS?

docs.page is an open-source documentation tool that helps you create instant, fast, beautiful, and responsive documentation websites with minimal configuration. It is an open-source project developed by Invertase, a company known for creating developer tools and SDKs.

docs.page is designed to streamline the process of publishing documentation by sourcing content directly from public GitHub repositories.

Key Features:

• Zero configuration: you create a 'docs.json' file and a 'docs' directory. Inside the docs directory, you can create files using the .mdx extension, and docs.page will generate your documentation site.

• Customizable: docs.page allows you to add your logo, social links, theme, analytics, navigation, and more through a simple configuration file.

• Live previews: enables viewing of documentation for any branch, pull request, or specific commit, facilitating real-time collaboration and review.

• Hot reload: the Hot Reload feature provides real-time previews of documentation changes while editing Markdown (.mdx) files. This feature enhances the local development workflow, enabling instant updates without manual refreshes or rebuilds.

• GitHub bot integration: provides a GitHub bot that automatically generates URLs for pull request documentation previews.

• MDX support: you can write documentation in Markdown to utilize MDX, which enables you to use React components, such as tabs, Cards, Tweets, and Steps, directly within your Markdown file.

• Search functionality: integrates with DocSearch to offer full-text search capabilities within your documentation.

• Responsive resign: ensures that your documentation is accessible and visually appealing across a range of devices and screen sizes.

• Dark/light mode: offers theme customization to switch between dark and light modes.

• Code block highlighting: provides syntax highlighting and content copying features for code blocks.

Check out the code available in my GitHub repository.

Table of Contents:

• How Does docs.page Work?

• How to Enable Live Preview in docs.page

• How to Configure docs.page

• How to Use Pre-built Components in docs.page

• How to Diagnose Errors in docs.page

• How to Use Frontmatter

• How to Add Assets to Your Docs

• How to Publish Your Documentation Website

• How can you live preview your upcoming changes to your documentation website?

• Conclusion

How Does docs.page Work?

You can easily start creating your documentation page using the docs.page CLI. It helps you set up a local documentation project by running the following command:

pnpm dlx @docs.page/cli init docs.page

The command output appears as follows:

pnpm dlx @docs.page/cli init docs.page
? Are you sure you want to setup and install docs.page in /home/officialrajdeepsingh/medium/docs.page? yes
Files created:
 - docs.json: Configuration file for your documentation site
 - docs/index.mdx: The home page of your documentation site
 - docs/next-steps.mdx: A page to help you get started with docs.page

Initialization complete. To preview your documentation site, vist https://docs.page/preview in your browser.

After creating your project with the docs.page CLI, your project structure should appear as follows:

.
├── docs
│   ├── index.mdx
│   └── next-steps.mdx
└── docs.json

2 directories, 3 files

The docs folder contains the Markdown file for your documentation, and the docs.json file includes the configuration for your website, such as the header, sidebar, logo, theme, and other settings.

How to Enable Live Preview in docs.page

You can set up live preview of your local documentation in real-time in the browser – but it's a little different: you don't need to run any development commands on your laptop or machine.

To open the live preview of your local documentation, first visit https://docs.page and click the Local Preview button.

Next, select the documentation project on your laptop or machine and click the "Select Directory" button.

After clicking the "Select Directory" button, a new window will open depending on your operating system. Its UI may appear different. Then you need to select the project.

After selecting the folder, you will see the following alert message in the browser (“Let site view files?”). To view the live preview of your documentation website, click the "View files" button.

Now you can see a local live preview of the documentation website in the browser, and any changes you make locally will instantly reflect in the browser. By default, your documentation website should appear as follows:

Next, you’ll learn about configuring the Logo, Theme, Header, Social Links, Sidebar, SEO, search, and more on your docs. You’ll also learn how to use the pre-built components, Front Matter, and assets on docs.page, and finally, how to deploy your documentation website.

How to Configure docs.page

The docs.json file is the primary file for configuring your documentation. Below is a list of all available configuration options, which you can use to modify the logos, theme, analytics, and more on your docs.

Properties

• Basic properties

• Logo

• Theme

• Header

• Anchors

• Social Links

• SEO

• Variables

• Search

• Scripts

• Content

• Tabs

• Sidebar

There’s so much you can configure using docs.page – but in this tutorial, we’ll focus on some of the most important options:

• Properties

• Basic Properties

• Logo

• Theme

• Header

• Social Links

• SEO

• Search

• Tabs

• Sidebar

Basic Properties

docs.page includes basic common properties, such as name, description, and favicon, which is very important for SEO.

• name (string): The name of your project. It appears in the header and is used for things like SEO metadata.

• description (string): A summary of your project. This is used in meta tags and social preview images.

• favicon (string | Favicon object): Specifies the favicon shown in the browser tab. You can provide either a single string URL or use a Favicon object to define different icons for light and dark modes:

  • light (string): URL for the favicon in light mode.

  • dark (string): URL for the favicon in dark mode.

// docs.json
{
  "name": "Docs.page",
  "description": "Ship documentation, like you ship code",
  "favicon": "https://static.invertase.io/assets/docs.page/docs-page-logo.png",
   # or
  "favicon": {
    "light": "https://cdn-icons-png.flaticon.com/24/9664/9664027.png",
    "dark": "https://cdn-icons-png.flaticon.com/24/9643/9643115.png"
  }
}

Logo

Now it’s time to configure the logo for your documentation, which will appear in the header and be used for social preview images.

The minimum height of the logo must be 24px. You can provide URLS for both a light and a dark logo. If you only provide a light or dark logo, and it doesn't work, you may experience issues where your logo doesn't appear on the website when toggling the theme.

You can add the logo to the documentation in two ways:

• First way:

// docs.json
{
  "name": "My Docs",
  "logo": "https://cdn-icons-png.flaticon.com/24/2702/2702154.png",
}

• Second way:

// docs.json
{
  "name": "My Docs",
  "logo": {
    "light": "https://cdn-icons-png.flaticon.com/24/2702/2702154.png",
    "dark": "https://cdn-icons-png.flaticon.com/24/2702/2702172.png"
  }
}

Theme

Configuring the theme in your documentation is easy. If you don’t provide a theme, the default theme will be used in your documentation.

docs.page includes a theme property in docs.json, which holds a Theme object as its value with the properties defaultTheme, primary, primaryLight, backgroundLight, and backgroundDark.

• defaultTheme: You can select a theme, dark or light.

• primary: The primary colour is used for links, buttons, and other interactive elements.

• primaryLight: The primaryLight colour option is used in light mode. If your primary light option is not specified in the docs.json file, then the primary colour will be used.

• primaryDark: The primaryDark colour option is used in dark mode. If your primaryDark option is not specified in the docs.json file, then the primary color will be used.

• backgroundLight: The backgroundLight option is used to specify the background color of your documentation in light mode.

• backgroundDark: The backgroundDark option is used to specify the background color of your documentation in dark mode.

// docs.json
{
  "theme": {
    "defaultTheme": "dark",
    "primary": "#de40eb",
    "primaryLight": "#BFA213",
    "backgroundLight": "#e0cfff",
    "backgroundDark": "#00101f"
  },
}

Header

Configuring the header in your documentation includes the following properties: showName, showThemeToggle, showGitHubCard, and links.

• showName: The showName option displays the documentation name next to the logo in the header and defaults it is true.

• showThemeToggle: The showThemeToggle option displays the theme toggle button in the header (and defaults to true).

• showGitHubCard: The showGitHubCard option displays the GitHub card in the header and defaults to true.

• Links: The links option contains an array of Link objects to display a navigation in the header of your documentation.

// docs.json
{
  "header": {
    "showName": false,
    "showGitHubCard": false,
    "links": [
      {
        "title": "GitHub",
        "href": "https://github.com/officialrajdeepsingh/docs-page-demo"
      },
      {
        "title": "X",
        "href": "https://x.com/Official_R_deep"
      },
      {
        "title": "Linkedin",
        "href": "https://www.linkedin.com/in/officalrajdeepsingh"
      }
    ]
  }
}

Social Links

The social option contains an object of key-value pairs where the key represents the social platform and the value corresponds to the username or ID. Here’s how you can add them:

// docs.json
{
  "social": {
    "github": "officialrajdeepsingh/docs-page-demo",
    "x": "@Official_R_deep",
    "linkedin": "officalrajdeepsingh"
  }
}

SEO

The SEO option configures the SEO settings for your documentation. The noindex option tells search engines not to index your documentation, and it defaults to false.

// docs.json
{
  noindex: true
}

Search

To enable search functionality on your documentation site, you can integrate Algolia DocSearch by configuring the docsearch object in your docs.json file like this:

// docs.json
{
 "search": {
    "docsearch": {
      "appId": "YOUR_APP_ID",
      "apiKey": "YOUR_API_KEY",
      "indexName": "YOUR_INDEX_NAME"
    }
  }
}

Tabs

Tabs are an array of objects displayed at the top of your documentation website.

Properties

Each Tab object includes the following properties:

• id (string, required): A unique identifier for the tab.

• title (string, required): The text label displayed on the tab.

• href (string, required): The URL to navigate to when the tab is clicked.

• locale (string, optional): If set, this tab is displayed only when viewing documentation for the specified locale.

Here’s an example of a couple tabs:

{
  "tabs": [
    {
      "id": "root",
      "title": "Documentation",
      "href": "/"
    },
    {
      "id": "components",
      "title": "Components",
      "href": "/components"
    }
  ],
}

Sidebar

To display the sidebar on your website, you can configure or define it in the docs.json file your documentation, which will appear in the sidebar of your site.

Essentially, a sidebar is a list of links that appears on the side of your documentation. You can organize links using groups and pages by providing an array of sidebar objects.

Options:

• pages: The pages option takes a list of page links to display in the sidebar. It accepts the following options:

  • title (required): The title of the sidebar item.

  • href (required): The URL to link to when the sidebar item is clicked.

  • icon (optional): The icon to display next to the sidebar item.

• group (string): The title of the group under which the sidebar item will be displayed. If not provided, the item will appear at the top level of the sidebar.

• href (string): The URL the sidebar item will link to when clicked.

• icon (string): The name of the icon to display next to the sidebar item.

• tab (string): If set, the sidebar item will only be shown when a specific tab (matching the provided tab ID) is active.

// docs.json
{
"sidebar": [
    {
      "pages": [
        {
          "title": "Overview",
          "href": "/",
          "icon": "book"
        },
        {
          "title": "Configuration",
          "href": "/configuration",
          "icon": "gear"
        }
      ]
    },
    {
      "group": "Components",
      "icon": "grip",
      "pages": [
        {
          "title": "Getting Started",
          "href": "/components",
          "icon": "rocket"
        },
        {
          "title": "Accordion",
          "href": "/components/accordion",
          "icon": "square-caret-down"
        },
        {
          "title": "Callouts",
          "href": "/components/callouts",
          "icon": "bullhorn"
        },
        {
          "title": "Cards",
          "href": "/components/cards",
          "icon": "square-full"
        }
      ]
    }
  ]
}

If you want to learn more about this, check out the documentation here.

How to Use Pre-built Components in docs.page

docs.page comes with 15 pre-built components, so you don't need to import components into your MDX file. You can use them directly in your MDX file.

In the following example, I’m using the Info Callout component directly within the MDX file, without importing it.

// index.mdx
---
title: Welcome to docs.page!
description: Get started with docs.page
---

Welcome to docs.page! The init command you just ran has created a basic file struture in your project to help you get started.

## Walkthrough

### Configuration

In the root of your directory a new `docs.json` file has been created. This file is used to configure your documentation site. You can customize the name, description, and sidebar, theme, logos and more using this file.


<Info>Here's a basic example of what the file looks like: </Info>

How to Diagnose Errors in docs.page

If you encounter any errors on your documentation website, you can view all the errors by clicking the diagnostics button.

How to Use Frontmatter

Front matter is a block of YAML placed at the beginning of a Markdown file, enclosed between triple-dash (---) lines.

Frontmatter is a way to customise the metadata page directly within your Markdown files, and most importantly, frontmatter is used for SEO.

# docs/getting-started.mdx
---
title: Welcome to Awesome Project
description: Some awesome docs!
---

# Welcome!

Below is a list of some of the important frontmatter properties in docs.page, including their type and default values:

• title (string): The page’s title used in metadata, social cards, and displayed as the main heading.

• description (string): A summary of the page appears in metadata for SEO and link previews.

• image (string): URL of an asset used in social cards and (if enabled) shown at the top of the page.

• redirect (string): A URL to forward visitors to. When set, the page’s content is bypassed.

• showPageTitle (boolean): Toggle whether the page title appears as a heading at the top.

• showPageImage (boolean): Toggle whether the front-matter image is rendered at the top.

• noindex (boolean): If true, instructs search engines not to index the page.

Refer to the documentation for more detail and other frontmatter property information.

How to Add Assets to Your Docs

You can include assets, such as images and videos, in your documentation. You can add both remote and local assets.

Remote Assets

To add remote assets to your documentation, you can reference them directly in your markdown files.

For example, to include an image from a URL:

# getting-started.mdx
---
title: Welcome to get started
description: Some awesome docs!
---

# Welcome!

![Natural](https://cdn.pixabay.com/photo/2023/04/19/19/11/lake-7938396_960_720.jpg)

Local Assets

To use local assets in your documentation, create an assets folder inside the docs/ directory. Then, add images and videos to the assets folder and reference them in your Markdown files.

Check out the following to better understand:

docs/
  assets/
    natural.png
  index.mdx

Within your markdown file, you can reference the image using a relative path:

![Description](/assets/natural.png)

Different between Local vs Remote Assets

Local assets (PNG, JPG, PDF, and so on) are files stored within your project's public folder, while remote assets are files hosted on an external server. You can access your local assets using your domain URL.

![Natural](./assets/logo.png)

On the other hand, remote assets are stored on a different server (image hosting), as I mentioned. You can access remote assets with a full URL.

The best examples of remote assets include images from Unsplash, Pixabay, and Pexels that can be used directly in your MDX file.

![Natural](https://images.unsplash.com/photo-1728044849236-5e8a061e1895)

You can use remote and local assets based on your requirements – both have advantages and disadvantages. With remote assets, you can add an image directly in your mdx file. When using local assets, you add an image to the public folder and then reference it in your mdx file.

How to Publish Your Documentation Website

With docs.page, you can easily publish your documentation website. No configuration is required – once your documentation website is ready, you can just push your local code to a GitHub repository.

You can now access your documentation website immediately via the docs.page domain.

For example, if your GitHub repository is officialrajdeepsingh/docs-page-demo, your documentation will be available at https://docs.page/officialrajdeepsingh/docs-page-demo.

How to Live Preview Upcoming Changes to Your Docs Website

You can view previews of upcoming changes to your documentation before going public. As your documentation website grows, use the docs.page Github app – any pull request you create in your Github repository automatically generates a unique live preview URL.

To configure the docs page of the GitHub application in your repository, follow these steps:

1. Go to https://github.com/apps/docs-page

2. Click on the install button.

3. Select the GitHub account

4. Select All and single repository.

5. Click on the install button

6. Next, enter the password and OTP.

7. Now if your application is successful, install it in your repository.

Whenever you or another developer create a pull request in your repository, the docs page application creates live previews for you.

Conclusion

docs.page is a free, open-source project that allows you to create instant, fast, and beautiful documentation without requiring any configuration.

I think docs.page offers the best solution for documentation. You can easily set up and deploy your documentation website with the help of docs.page cloud service.

For now, it’s completely free to deploy a documentation website with a docs.page, and I hope it stays that way.

If docs.page ever decides to charge for their services, that could be troublesome. Hopefully, in that case, they’ll provide a clear guide on how to deploy your website on another cloud platform.

Basically, the Lazygit tool is a wrapper for the Git command line that replaces it with a UI. Instead of typing out Git commands again and again in your terminal, you can use keyboard shortcuts to commit, push, pull, create, edit, and delete branches in your project.

In simple terms, Lazygit helps you increase your productivity while working with Git.

In this article, we'll walk through the essential features of Lazygit, and I’ll show you how it works.

Table of Contents:

1. How to Install Lazygit

2. How to Use Lazygit

3. Shortcuts and Key Mappings in Lazygit

4. Other Keybindings in Lazygit

5. Conclusion

How to Install Lazygit

Before we start, you’ll need to make sure it’s installed on your machine. You can install the tool in your system using the following methods (depending on your system):

Homebrew

You can install lazygit in macOS using Homebrew like this:

brew install lazygit

Scoop (Windows)

You can install lazygit in Windows using Scoop like this:

# Add the extras bucket
scoop bucket add extras

# Install lazygit
scoop install lazygit

Arch Linux

You can install lazygit in Arch using Pacman like this:

sudo pacman -S lazygit

Ubuntu and Debian

You can install lazygit in Ubuntu and Debian using the following command:

LAZYGIT_VERSION=$(curl -s "https://api.github.com/repos/jesseduffield/lazygit/releases/latest" | \grep -Po '"tag_name": *"v\K[^"]*')
curl -Lo lazygit.tar.gz "https://github.com/jesseduffield/lazygit/releases/download/v${LAZYGIT_VERSION}/lazygit_${LAZYGIT_VERSION}_Linux_x86_64.tar.gz"
tar xf lazygit.tar.gz lazygit
sudo install lazygit -D -t /usr/local/bin/

Verify the correct installation of lazygit:

lazygit --version

The command output looks like this:

➜  lazygit --version
commit=, build date=, build source=nix, version=0.44.1, os=linux, arch=amd64, git version=2.47.0

Fedora and RHEL

You can install lazygit in Fedora and RHEL using DNF like this:

sudo dnf copr enable atim/lazygit -y
sudo dnf install lazygit

NixOS

You can install lazygit in NixOS using the following method:

# with nix-shell
nix-shell -p lazygit

# with nix-env
nix-env -iA lazygit

# with /etc/nixos/configuration.nix
environment.systemPackages = [
  pkgs.lazygit
];
# or with enable lazygit flakes
nix run nixpkgs#lazygit

How to Use Lazygit

To use Lazygit, you don’t need any advanced knowledge about Lazygit or the Git CLI. If you are a beginner, that’s okay – I’ll walk you through the process and the basics here.

The main thing to understand is how the key mappings (shortcut keys) work. In this tutorial, I won’t discuss every key mapping, but I’ll teach you about some of the most common Lazygit key mappings which you’ll use on a daily basis. They’ll help you build a solid base for using the tool effectively.

To use Lazygit, first open the terminal you use. For example, I’m using the GNOME distro, so I’ll use the Ptyxis terminal.

Type the lazygit command in your terminal:

lazygit

The command output should look like this in your terminal:

The Lazygit UI is divided into six panels, or sections. Each panel serves a specific use case. Let’s explore these panels in more detail. You can see them highlighted in the image below:

Panels or Sections in Lazygit

As I mentioned above, there are six main panels in Lazygit. They are:

1. Status

2. Files

3. Branches

4. Commits

5. Stash

6. Previews

The most important panels in Lazygit are files, branches, and commits, but we’ll examine each of the six now.

Status panel

The status panel provides an overview of your current repository and the current checked-out branch, including local and remote changes.

Also, when you click on the status panel text, it opens a new tab or panel where it shows the recently opened repository list.

Files panel

The Files panel shows lists of the files in your repository that have been modified or changed. You can see files that you’ve deleted or discarded and unstaged.

Branches panel

The Branches panel shows lists of local and remote branches which are available in this repository.

Commits panel

The Commits panel shows a list of commits in the current branch, which allows you to view, checkout, or interact with (view/undo/and so on) specific commits.

Stashes panel

The Stashes panel helps you manage your stashed changes, allowing you to apply, drop, or view them. Git stash is a location for storing uncommitted changes (modified, staged, or untracked files) in a hidden place, letting you switch branches without committing or discarding them.

Preview panel

The preview panel lets you preview unstaged changes, commits, logs, file content, and so on in Lazygit.

To switch between panels, use the left and right arrow keys or the specific keybindings displayed at the top of each panel.

Press 1 to open the Status panel, 2 for Files, 3 for Branches, 4 for Commits, and 5 for the Stash panel.

Shortcuts and Key Mappings in Lazygit

Lazygit is especially popular because of its shortcuts. You don’t need to write the same Git commands in the terminal over and over. Rather, you just need to use a shortcut.

For example, usually when you commit a file, you’ll first add the file using git add and then commit the file using git commit.

But in Lazygit, you just have to select the file using your mouse or the up and down keys and press space to commit the file.

In Lazygit, everything works around the shortcut commands, and you use shortcuts to perform common Git operations. Here are a few essential commands we’ll go over in this tutorial:

• a – Stage or unstage all the files available in the Files panel.

• space (file panel) – Stage or unstage a single file in the Files panel.

• c – Commit staged changes by opening a commit message editor.

• p – Push commits to the remote repository.

• P – Pull changes from the remote repository.

• z – Undo the commit.

• s – Stash changes, allowing you to switch branches or perform other operations.

• S – View and apply stashed changes.

• n – Create a new branch.

• d – Delete your branch.

• y – Copy to clipboard.

• M – Merge branch.

• space (branches panel) – Check out the selected target branch.

• e – Edit or open the file in an external editor.

• q – Quit Lazygit and return to the terminal.

• d – Discard any changes in the file.

• ? – Open the keybinding menu.

Now let’s go over these shortcuts so you can understand how they work and see them in action.

How to Commit a File

To commit a file in Lazygit, first select the file you need by pressing the space key or the a key or double-clicking on the file. Then press c, and a new panel should open. There, you can add a message and hit enter to commit the file.

How to Pull and Push Code

To pull remote code from the Git server (Github, GitLab, Gitea, and so on), you can press p (lower case p):

To push local code into a Git server, you can press P (upper case P):

How to Create and Delete a Branch

To create a new branch in Lazygit, press n. A new panel will open where you’ll add the name of the branch and hit Enter.

To delete a branch, press d and then specify whether you want to delete the branch in a local or remote repository. In the following example, I’m deleting a local branch.

Note: To delete and create a new branch in Lazygit, first select the branch panel and then press the corresponding shortcut key for deleting a branch. Press the d key to delete, and then to create a branch press the n key. Otherwise, it won’t work.

How to Undo a Commit

To undo the last commit in Lazygit, just press z. A new panel will open, showing the details of the commit you are undoing. Then, hit Enter.

How to Merge a Branch

To merge a branch, press M (capital M). To open the merge options, choose the merge type, then hit Enter.

Merge type:

• Merge: A standard merge, preserving the branch history.

• Squash merge: Combines all commits from the branch into a single commit on the target branch.

• Squash merge and leave uncommitted: Same as squash merge, but leaves the changes uncommitted.

How to Resolve Merge Conflicts

To resolve merge conflicts in Lazygit, first merge a branch by pressing M, then choose the merge type (which I describe in the subsection on how to merge a branch) and hit Enter.

If any merge conflicts occur, the conflicting file(s) appear in the files panel. Press Enter to view the merge conflicts in the preview panel and navigate between conflicts using the up and down keys. Select the correct merge conflicts, press the space key, and your merge issue will be resolved.

How to Discard Changes

To discard or drop any changes in a file or commit, press d.

How to Copy

To copy a file name, path, commit hash, message, URL, author, or any other details, first select the commit or file, then press y to copy the information.

Other Keybindings in Lazygit

There are other keybindings in Lazygit which I did not discuss in this article. To learn about every keybinding, you can check out the keybindings menu. Open the keybindings menu and press the ?.

When you open the keybindings help menu, it changes according to the panel you’re in.

Conclusion

Lazygit helps you become more productive when working with Git or Git commands. As a beginner, starting with Lazygit can be somewhat challenging because of its key mappings, but once you get the hang of them, they’re pretty easy to remember and use.

If you are a first-time Lazygit user, my suggestion is to avoid using Lazygit on a working repository. Instead, create a demo repository and try it out/practice.

To learn more about LazyGit keybindings or shortcuts, you can refer to the Lazygit documentation. You can also check out the following YouTube tutorials for beginners:

• LazyGIt - A Faster, Easier Way to Use Git on Terminal & NeoVim

• Lazygit - The Best Way To Use Git On The Terminal & Neovim

• My new favorite way to use Git

• LazyGit: Effortless Git in Your Terminal!

In simple terms, the GitHub workflow creates an environment (virtual machine-based on the runner) to test, build, and deploy your code into the cloud based on the action that you describe in the GitHub Action file.

This tutorial teaches you how to add a GitHub Action, providing an example and step-by-step guidance. It is suitable for both beginners and intermediate developers.

Table of Contents:

1. Prerequisites

2. Key GitHub Actions Concepts

3. How to Create a GitHub Action in Your Repository

   • Create a GitHub Action Using the GitHub UI

   • Create a GitHub Action Locally with Your IDE

4. GitHub Actions Syntax

5. GitHub Actions Examples

6. Conclusion

Prerequisites

To get the most out of this article, you should have at least a basic knowledge of how to use GitHub and YAML. If you don't know GitHub fundamentals, check out this in-depth tutorial on Git and GitHub. And here’s an introduction to YAML.

You’ll also need to understand the main concepts behind events, workflows, jobs, and runners and why they’re important when creating a GitHub Action.

These are the key ingredients of GitHub actions, so we’ll go through them one by one before diving into the primary part of the tutorial.

Key GitHub Actions Concepts

Workflows

A workflow is a configurable automated process that runs one or more jobs. It is created with a YAML file in your repository and runs when an event triggers it. Workflows can also be triggered manually or on a defined schedule.

Workflows are defined in the .github/workflows directory in a repository. In the repository, you can create multiple workflows that perform different tasks, such as:

1. Building and testing pull requests

2. Deploying your application on the cloud

3. Running a test on every pull request

Events

An event is a specific activity in a repository that triggers or runs a workflow in your GitHub repository. For example, when you push code to the repository, it triggers the push event. The same happens when you create a new issue – it triggers the issues event. And when somebody makes a pull request in your repository, it triggers the pull_request event.

These are some common GitHub Action events:

1. Push

2. pull_request

3. release

4. label

5. issues

6. milestone

7. label

The push, release, and pull_request events are the most common events. To read more about events, you can check out the GitHub documentation.

It’s a good idea to specify the event type in a GitHub Action. For example, specifying the pull_request event will trigger the action whenever any user creates a pull request in the GitHub repository.

# .github/workflows/demo.yml

on:
  issues:
    types: [opened, edited, milestoned]

  pull_request:
    types:
      - opened
    branches:
      - 'releases/**'

This is helpful because, if you don’t declare a specific event activity type in your event type, it can lead to unnecessary resources getting used. The GitHub Action will be triggered with every new pull request – so it’s best to define which type of event you’re using.

Jobs

GitHub Action jobs run in parallel by default. A GitHub Action workflow runs one or more jobs, each containing a set of steps that execute commands or actions. Here’s an example:

# .github/workflows/demo.yml

name: Demo Workflows

on:
   push:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:

jobs:

You can set one job to depend on (an)other job(s). If jobs don’t have dependencies, they’ll run in parallel. When one job depends on another, it will wait for that job to finish before it starts.

# .github/workflows/demo.yml

jobs:
  build:
    name: Build
    needs: [ Development ]
    steps:
      - name: Build and deploy on Cloud
  dev:
    name: Development
    steps:
      - name: Run the developer

  Test:
    needs: [ build, dev ]
    name: Testing
    steps:
      - name: Testing the application

Runners

Runners are servers that execute workflows when triggered. Each runner can handle only one job at a time. GitHub offers runners for Ubuntu Linux, Microsoft Windows, and MacOS to run your workflows.

# .github/workflows/demo.yml

name: Demo workflows

on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
   push:
    branches: [ "main" ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

To define the runners, specify the runner value in the runs-on option. You can provide it as a single string or an array of strings.

# .github/workflows/demo.yml

# String
runs-on: ubuntu-latest
# Array of string
runs-on: [ ubuntu-latest, windows-latest, macos-latest ]

Now that you’re familiar with the key elements of GitHub Actions and how they work, let’s see how to use Actions in practice.

How to Create a GitHub Action in Your Repository

You can create a GitHub Action in GitHub very easily. There are two ways to do it:

1. Using the Github UI

2. Locally with your IDE

Many developers use the GitHub UI to create an Action. This is a common way to create an Action. You don't need to create a .github/workflow folder when you use the GitHub UI. GitHub automatically creates this folder for you. On the other hand, for complex Github actions, you'll typically use your IDE.

Let’s look at each approach now.

Create a GitHub Action Using the GitHub UI

First, go to the GitHub repository where you want to create your GitHub Action.

To create the action, follow these steps:

1. Click on the Action Tab

Click on the Action tab to create a GitHub Action. You’ll see the following page:

2. Select the workflow action

GitHub suggestions automatically work according to the nature of your project. Select the GitHub workflow and click on the configure button to create your action.

3. Create the GitHub workflow

You’ll see the following page where you can edit and create your action. Click on the commit change button to save the action.

And that’s it – you’ve created your GitHub Action.

Create a GitHub Action Locally with Your IDE

First, open your project in your current IDE, such as VS Code, Neovim, Vim, or whatever. Then, create a .github/workflow/name-of-workflow.yml file in your project. Copy and paste the following code and save and push your local code into the GitHub repository.

Following the GitHub workflow action example code is printed a hello world message.

# .github/workflows/demo.yml

name: CI

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v4

      # Runs a single command using the runners shell
      - name: Run a one-line script
        run: echo Hello, world!

I’m using the Neovim IDE to create a .github/workflow/demo.yml file. It looks like this.

GitHub Actions Syntax

To create a GitHub Action, it’s important to understand the GitHub Action syntax. In this section, you’ll learn some of the most common syntax you’ll use to create your Actions.

We’ll work with this example Action and go through it part by part below:

# .github/workflows/demo.yml

name: Github Action Template 

on:

  pull_request:
    branches: [ "main" ]

  schedule:
    - cron:  '30 5,17 * * *'

  workflow_call:
    inputs:
      username:
        description: 'A username passed from the caller workflow'
        default: 'john-doe'
        required: false
        type: string

  permissions:
    actions: read|write|none

  # permissions : read|write|none

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:

  # This workflow contains a single job called "build"

  build:

    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job

    steps:

      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v4
        if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
        shell: zsh
        name: NPM Install Package
        run: npm install
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          first_name: Github
          last_name: Action
          args: The ${{ github.event_name }} event triggered this step.
          entrypoint: /bin/echo

Now, let’s understand each option that you can see in this GitHub Action example workflow:

1. name: The name describes the workflow name.

2. pull_request: The pull request is part of the event type. It means somebody added a pull request in your repository and the following workflow was run.

3. schedule: With a schedule, you can define the time schedule in your workflows. You can schedule a workflow to run at certain tasks on specific UTC times or based on intervals after five minutes, and so on.

4. workflow_call: This defines the inputs and outputs for a reusable workflow.

5. permissions: In GitHub, certain tasks need special permissions when working with the GitHub app and GitHub API. For example, for issues, write permission permits a user to add a comment to an issue. For other permissions, you can check out the documentation.

6. jobs: The jobs option runs one or more jobs in your GitHub Action, each containing a set of steps that execute commands or actions.

7. runs-on: The runs-on option defines the type of machine to run the job on.

8. steps: The jobs contain a sequence of tasks called steps. Steps can run commands, set tasks, or an action in your repository.

9. name: The name option is used to set the name of the job, which is displayed in the GitHub UI.

10. if: the if option works similarly to an if conditional. It prevents a step from running unless a condition is met.

11. shell: The shell option allows you to define a custom shell.

12. run: The run option helps run commands in the operating system's shell. For example, run : ls, run : pwd, and so on.

13. uses: With the uses option, you can run reusable units of code or other packages. You usually use it to run a GitHub package published by another developer on the GitHub marketplace. Most package developers use JavaScript or Docker container files.

14. with: the with option accepts a value as a map with a key/value pair. It has two sub-options: args and an entrypoint. The entrypoint is used to define the entry file for Dockerfile. The args option will be passed to the container's entrypoint.

You’ll typically use this syntax to create your GitHub Actions. In the next section, you’ll learn how to use it to actually build a GitHub Action.

For advanced GitHub Action syntax, you can check out the Github documentation.

GitHub Actions Examples

To better understand how GitHub Actions work, let’s build four examples of a GitHub Action workflow. These are common examples that many developers use and will teach you how GitHub Actions work.

Node Setup

In the following GitHub Action, we’ll set up a Node.js environment for our application. Once you’ve done that, you can test and deploy your Node.js application.

# .github/workflows/nodejs.yml

name: Setup Node.js Env

on:
  push:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version:  21
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

For our example, we’re running our action on an Ubuntu machine. The GitHub action is triggered whenever you (or someone) push code into the repository. The actions/checkout@v4 extension sets the $GITHUB_WORKSPACE environment variable to your working directory.

The actions/setup-node@v4 extension sets up the Node.js environment, and the GitHub run option executes the Linux command.

Deno Setup

In the following GitHub Action, we’ll set up a Deno environment for our application. You can test and analyse (using deno lint) the code for errors, stylistic issues, and so on.

name: Deno

on:
  push:
    branches: ["main"]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Setup repo
        uses: actions/checkout@v4

      - name: Setup Deno
        uses: denoland/setup-deno@v2
        with:
          deno-version: v2.1.5

      - name: Run linter
        run: deno lint

      - name: Run tests
        run: deno test -A

For this example, we’re running our action on an Ubuntu machine. The GitHub action is triggered whenever you (or someone) push code into the repository. The actions/checkout@v4 extension sets the $GITHUB_WORKSPACE environment variable to your working directory.

The denoland/setup-deno@v2 extension sets up the Deno environment and the GitHub run option executes the Linux command.

Zip Files

In the following example, we’ll combine the dist folder and the manifest.json file into a zip archive. Then we’ll save the zipped file as an artifact for later use or download:

name: Zip Files

on:
  release:
    types: [published]

jobs:
  zip-files:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: vimtor/action-zip@v1.2
        with:
          files: dist/ manifest.json
          dest: build.zip

       - uses: actions/upload-artifact@v4
         with:
           name: zip file
           path: ${{ github.workspace }}/build.zip

For this example, we’re running our action on an Ubuntu machine. The GitHub Action is triggered whenever someone pushes code into the repository. The actions/checkout@v4 extension sets the $GITHUB_WORKSPACE environment variable to your working directory.

The vimtor/action-zip@v1.2 extension or package converts files into a zip folder. The actions/upload-artifact@v4 package uploads artifacts during a workflow run.

Deploy a Static Website

The following GitHub Actions example demonstrates how to deploy an HTML website to GitHub Pages.

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:

  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:

      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: '.'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

For this example, we’re running our action on an Ubuntu machine. The GitHub action is triggered whenever you push code to the repository. The actions/checkout@v4 extension sets the $GITHUB_WORKSPACE environment variable to your working directory.

The actions/configure-pages@v5 package helps you configure GitHub Pages and allows you to gather metadata about your website. For more detail, refer to the configure-pages action documentation.

The actions/upload-pages-artifact@v3 package helps you to package and upload artifacts that can be deployed to GitHub Pages.

The actions/deploy-pages@v4 package is used to deploy your website to GitHub Pages.

Conclusion

Github Actions is a large topic. To more fully understand them, you can start with a basic Action example and then move on to more advanced Actions.

When you’re using Github Actions, the biggest problem is waiting for the results. For example, creating and updating the date on which the GitHub Action file pushes code into GitHub and then waiting for the GitHub Action result. It can be a time-consuming task, so you can use the act CLI tool instead of running GitHub Actions Locally on a laptop or computer.

I have published an in-depth article on freeCodeCamp on how to use the Act CLI tool if you want to read more about that.

Thanks for reading!

Small open-source project repositories are easily maintained without using additional functionality because few developers work on them.

However, when working with medium or large open-source projects, the main problem lies in how to manage them.

With many developers contributing at the same time and the developer community rapidly expanding day by day, this becomes a significant challenge.

GitHub, GitLab, Gitea, and so on, have similar functionalities that help you and your team to manage your project more efficiently. Without relying on other software and tools, you can handle your project with your repository.

In this tutorial, we'll discuss three basic GitHub features that can help you to manage your repository more efficiently without using any additional tools or services:

1. Labels

2. Projects

3. Milestones

GitHub, Gitlab, or Gitea all have similar functionalities with the same name.

How to Use Labels on GitHub

The label helps categorize issues, pull requests, and discussions. By default, GitHub comes with some built-in labels.

You can also create a custom label. You can use the label on any issue, pull request, or discussion within your repository.

You can find the list of default labels in the GitHub documentation.

How to Create a Label in Your Repository

Creating a custom label in the repository is very simple. There are different ways to make a label. You need to follow these common steps:

Go to your repository > then go to issues > then click on the labels button.

Next, click on the new label button and enter your label name, description and color.

How to Delete and Edit Labels on GitHub

To edit and delete a label, go to the issue page and click on the Label button. In the label page, you should see all the existing labels.

Click on the Edit button to edit a label, and click on the Delete button to delete a label.

You cannot delete multiple labels with GitHub.

How to Use GitHub Projects

The Github Projects tool is a versatile and flexible tool for planning and managing your repository work in one central location.

It functions similarly to a spreadsheet, task board, and road map, allowing you to plan and track your repository work in one place. The GitHub project is fully integrated with GitHub.

You can create and customize multiple views, filter, sort, and group your issues and pull requests, visualize work with charts, and add custom fields to track specific metadata.

You can assign users to specific issues, check issue statuses, and assign reviewers, among other functions.

GitHub projects come in two types: public and private.

• Public projects are visible to everyone, and the management team can make edits and changes to the project.

• Private projects, on the other hand, are not visible to others, and only the management team can edit and make changes to the project.

By default, projects are private in GitHub.

How to Create Projects on GitHub

Creating a project is a straightforward task. In some cases, the projects tab may not be visible on your repository. First, go to your repository section and enable the project.

After enabling projects on your repository, you should now be able to see a projects tab in your repository. Now click on the projects tab.

Your default project page looks like this. To create a new project, click on the dropdown icon and select the New Project, then click on the New Project option.

Next, select the templates for the project according to your requirements. Click on the view all button to view all available templates, or go with blank templates.

The template comes with pre-configuration based on what you choose.

I selected the feature release template for this tutorial. Next, enter your project name and click on the Create Project button.

Your project should be created based on the template you chose. Your project dashboard page may be different according to your template.

How to Delete and Edit Projects on GitHub

To edit and delete a project, go to the project page.

Then click on a project which you want to edit or delete. Clicking on the project title should take you to the project setting page.

In the project settings page, you can edit the project title and description, delete the project, close the project and also change the visibility of your project from private to public.

How to Use Milestones on GitHub

The milestone feature allows you to track the progress of issues or pull requests in a repository. With milestones, you can prioritize open issues and pull requests and set a due date for a group of related items.

In simple terms, milestones operate like a to-do list, where you can detail the amount of completed or pending work. It functions like a progress bar, helping your team manage the project more effectively and communicate the importance of specific issues to both your team and the open-source community.

Milestones allows the open-source community and your team to understand the status of completed or pending work, and the timeline for upcoming versions.

How to Create Milestones on GitHub

First, go to the repository and then to the issue page. Click on the milestones button.

Now, you should see your exciting milestones list. To create milestones, click on the new milestones button.

Enter the milestone title, due date and description and last, then click on the Create milestones button to make your milestone.

By default, your created milestone should look like this:

Our next task is to assign an issue to the milestone. Go to the issue and assign a milestone to it.

If you have multiple milestones, you can select one of them.

Verify whether the issue is attached or not to the milestone.

Now, you can attach or assign multiple issues with a single milestone. When you visit the milestone, you can see all the assigned milestone lists.

If you and your teammate close the issue, your progress bar is increased automatically. This can help your team and your community understand how much work has been completed.

How to Delete and Edit Milestones on GitHub

To edit and delete the milestones, you need to go to the issues page and click on the milestones button to see the available milestones.

To edit milestones, click on the edit button, and to delete the milestones, click on the delete button.

Conclusion

Labels, projects, and milestones are basic features useful for managing a project on GitHub. When you use them, you automatically learn about them.

Both milestones and projects are different, and you can not compare both at the same time because both provide different functionalities and working.

As I mentioned, a milestone is used to allow you to track the progress of issues or pull requests in a repository. On the other hand, a project is used to plan and manage your repository from one central location.

For small teams, I recommend milestones, and for the large team, I recommend using projects. You can also use both projects and milestones for better productivity.

I've written other article related to GitHub, and you can check them out here:

• https://www.freecodecamp.org/news/what-is-github-wiki-and-how-do-you-use-it/

• https://www.freecodecamp.org/news/github-flavored-markdown-syntax-examples/

• https://www.freecodecamp.org/news/how-to-run-github-actions-locally/

GitHub wikis are easy to start using without installing any other software. The best part is that the wiki is integrated with your GitHub repository.

You do not need any other tool – you just need to know how to use markdown, as you'll use it to write your wiki. (You can read all about that in my other article here.)

How to Start Using GitHub Wiki

You can start your GitHub wiki with just one click. Every GitHub repository has a Wiki tab in the menu at the top of the page. To start, click on it.

GitHub repository Page

The wiki tab is sometimes not shown by default in the GitHub repository nav bar. First, you'll need to enable wikis in your repository settings.

No wiki tab is shown.

To do that, go to your repository settings page, scroll down, and find the features section. Then enable wikis by checking the "Wikis" box.

Enable wiki

To initialize the wiki in your GitHub repository, create the home page in your wiki.

Initialize the wiki in GitHub.

When you click the "Create the first page" button, you'll be redirected to the editor page where you can create a home page in the wiki.

Create a home page and initialize the wiki.

Your wiki home page should now look like this:

Wiki home page

How to Clone a GitHub Wiki Locally

Sometimes, new developers are confused about how to clone the wiki locally. To do this, just copy the link where it says “Clone this wiki locally”, as you can see in the image below:

Copy the link to clone the GitHub wiki.

Copy that link and clone the GitHub wiki repository locally on your laptop or machine.

Now, you can make changes in the wiki, such as editing, updating, or changing documentation locally. After you finish any documentation changes, you can push your local wiki documentation to the GitHub wiki repository.

$ git clone https://github.com/officialrajdeepsingh/github-wiki-tutorial.wiki.git
Cloning into 'github-wiki-tutorial.wiki'...
remote: Enumerating objects: 6, done.
remote: Counting objects: 100% (6/6), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 6 (delta 1), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (6/6), done.
Resolving deltas: 100% (1/1), done.

How to Customize Your Wiki

Wikis have limited customization options for the sidebar, home page, and footer. But you can extend these options using HTML, CSS, and Markdown.

We have already discussed the home page, and now we'll discuss the footer and sidebar.

The footer and sidebar show or contain helpful links such as contact information, navigation links, social media links, and so on.

The footer is shown at the bottom of every page on your site, and the sidebar is typically a vertical column on the left or right side of a web page. Both are visible on all pages of the wiki.

How to create a custom sidebar

There are two ways to create a sidebar in the GitHub wiki.

1. With the GitHub UI
2. Locally in your IDE

We'll look at each method here so you can choose the one that works best for you.

With the GitHub UI

Create a sidebar

Go to the wiki home page and click on the “Add a custom sidebar” button to create a sidebar in your wiki.

Next, it will redirect you to the editor page to create a sidebar page. In the sidebar file, you can write markdown content such as navigation links, and so on. After that, click the save button.

_Create _Sidebar.md file._

Locally in your IDE

The second way is to clone your wiki locally and then create a _Sidebar.md
file in your wiki at the root level using VS Code or any other IDE which you like.

How to create a custom footer

You'll follow basically the same steps as in the sidebar section to create your custom wiki footer.

With the GitHub UI

Go to your wiki page and click on the “Add a custom footer” button to create a footer in your wiki.

Next, it will redirect you to the editor page to create a footer. In the footer file, you can write markdown content such as navigation links, and so on. After that, click the save button.

Create a footer

Locally in your IDE

The second way is to clone your wiki locally and then create a _Footer.md
file in your wiki at the root level using VS Code or any other IDE which you like.

What is a Page? How Do You Create a New Page in the Wiki?

In a wiki, a page has functionality similar to other CMSs, giving you the power to manage your content and documentation.

With the wiki page, you can divide your content or docs into different sections such as installation, configuration, and so on.

To create a new page, click on the new page button.

Create a new wiki page

It redirects you to the editor page, where you can add a title and content. After your writing is finished, click on the save button.

Create a wiki page

Your page looks like this in the wiki after it is published:

The Wiki page looks like this in the browser after publishing.

Everybody can access your pages section. Every page you publish is shown in the pages section on your wiki.

The page section shows the published page list.

How to Enable and Disable Collaboration in the Wiki

To enable collaboration for everyone in the wiki, go to your GitHub repository settings page, scroll down, find the features, and unselect the "Restrict editing to collaborators only" checkbox.

Enable Collaboration in the GitHub Wiki.

You can turn off collaboration for everyone, so that you and your team are the only ones responsible for updating, deleting, and editing the wiki.

To do this, you need to restrict editing for other users. Enabling the Restrict editing to collaborators only option quickly accomplishes this.

After there haven't been any edits, invite your team and give them access to it. Then just click the "Restrict editing to collaborators only" checkbox.

Disable Collaboration in the GitHub Wiki.

Why is GitHub Wiki So Useful?

GitHub wikis can be useful for everyone. You can start your documentation with a wiki in less than one minute. You do not need anything to start writing your documentation except basic knowledge of Markdown syntax.

Using GitHub wikis, you can just focus on writing basic documentation and on the project itself. GitHub wiki handles the rest of your documentation such as hosting concerns, search, and so on. Most importantly, for public repository wikis, it's totally free.

Many famous open-source projects use Wiki nowadays, such as hhvm, neovim, guard, foundation db, and others.

Check out the list of projects used in Wiki.

Conclusion

There are many documentation frameworks on the market, such as Nextra, Lume, Starlight, and Docusaurus. But they take some time to learn, configure, and set up.

Also, if you're still working on your coding skills and you aren't comfortable with tools like React, MDX, and so on, you'll need to take some time to learn them before using these more advanced documentation frameworks.

With GitHub Wiki, you can start creating your documentation right away, and you do not need to worry about deploying and hosting anything managed by GitHub.

GitHub Wiki is a great choice for small and early-stage projects. You and your team can focus on the project while composing straightforward documentation.

When writing on GitHub, you can use Markdown syntax and HTML elements to extend Markdown's functionality. You can use Markdown syntax everywhere in GitHub, such as in the README file, wiki, comments, pull requests, and when creating issues.

For every software developer, learning markdown is an essential step along the path of your career.

To enhance Markdown's basic features, GitHub added some custom functionalities and created GitHub-Flavored Markdown. With this, you can easily interact with other users in pull requests and issues by mentioning user, issue, and PR references and adding emoji.

This tutorial teaches you the basics of GitHub-Flavored Markdown so you can start using it in your projects.

All the code is available in the GitHub repository.

GitHub-Flavored Markdown Syntax

GitHub Flavored Markdown syntax is divided into two parts.

1. Basic Formatting Syntax
2. Advanced Formatting Syntax

We'll look at each one in detail below.

Basic Formatting Syntax

Basic formatting syntax applies to everyone. It contains fundamental essentials such as headings, code, images, quotes, links, and so on – things you'll need to know for writing.

1. Headings
2. Paragraphs
3. Comment
4. Styling text
5. Quotes
6. Code
7. Links
8. Images
9. Lists
10. Mentioning people and teams
11. Referencing issues and pull requests
12. Using emojis
13. Footnotes
14. Alerts

Note that the code samples mostly come from GitHub's documentation.

Headings

You can use the # symbol to create headings. One # creates an H1 heading, two create an H2 heading, and so on, like this:

# A first-level heading
## A second-level heading
### A third-level heading
#### A four-level heading
##### A five-level heading
###### A six-level heading

Paragraphs

To create paragraphs, you can use a blank line to separate one or more lines of text or paragraphs.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam est odio, commodo id diam sed, pulvinar sagittis tortor. Nam vestibulum purus eros. Sed congue, mi id pretium auctor, nibh augue iaculis arcu, eu tristique quam dolor at erat.

Quisque vel odio condimentum, mollis sem vitae, porta diam. Praesent ligula elit, condimentum eget ex sed, commodo sollicitudin sapien.


Proin volutpat faucibus nulla. Nullam eros sem, ultricies gravida nunc nec, dapibus posuere nisl. Nunc lacinia elementum turpis in pharetra. Aenean eu neque eros.

Comments

Comments are available in almost every programming language. They help developers write notes and add additional information to their code, helping other developers understand what's going on and how the code is working.

To add notes and additional information in Markdown, use the following syntax: <!--- Wrap text --->.

Here's an example:

<!-- This content will not appear in the rendered Markdown -->

Styling text

You can apply basic styles to your text, such as bold, italic, strikethrough, subscript, or superscript, to improve readability and convey your point more clearly.

1. For Bold, you can use the following syntax: **your text**
2. For italics, you can use the following syntax: *your text* or _your text_.
3. For strikethrough, you can use the following syntax: ~~your text~~
4. For subscript, you can use the following syntax: The subscript <sub> text </sub> is here.
5. For superscript, you can use the following syntax: The superscript <sup> text </sup> is here.

## Bold

**your text**

## italics

*your text*
_your text_

## strikethrough

~~your text~~

## subscript

The subscript <sub> text </sub> is here.

## superscript

The subscript <sup> text </sup> is here.

Quotes

A blockquote or quote is a sentence or paragraph formatted to let the reader know that you're quoting someone. To create a blockquote in Markdown, you can use the > symbol.

> Text that is a quote

Code

Markdown files support two types of code samples: inline and code block.

1. To add a code block in a Markdown file, use the following syntax: ``` your code ``` .
2. To add inline code to the Markdown file, use the following syntax: `your code` .

## Code Block

// ES5 syntax var multiply = function(x, y) { return x * y; };

// ES6 arrow function var multiply = (x, y) => { return x * y; };

// Or even simpler var multiply = (x, y) => x * y;

## Inline code 

JavaScript provides three different value comparison operations: strict equality using `===`, loose equality using `==`, and the `Object.is()` method.

To support code highlighting in a code block, you can add an optional language identifier after your triple backticks (like JavaScript in the example below):

## Code Block

```javascript

// ES5 syntax
var multiply = function(x, y) {
  return x * y;
};

// ES6 arrow function
var multiply = (x, y) => { return x * y; };

// Or even simpler
var multiply = (x, y) => x * y;

### Links

A markdown file divides links into two categories: **inline** and **relative**.

#### Inline links

To create an inline link in a Markdown file, wrap the link text in brackets `[ ]` followed immediately by the URL in parentheses `( )`.

```markdown
This site was built using [GitHub Pages](https://pages.github.com/).

Relative links

Relative links are defined similarly to inline links but they change in the [] section: the [] section contains the path of the file in your repository.

You use relative links to link two files: for example, to link the CONTRIBUTING file into the README file.

[Contribution guidelines](docs/CONTRIBUTING.md)

Relative links starting with / will be relative to the repository root. You can use all relative link operands, such as ./ and ../.:

[Contribution guidelines](../docs/CONTRIBUTING.md)

Images

To add an image in a markdown file, add a ! and then wrap the alt text in []. Then, wrap the image link with parentheses ().

It looks like this:

![Markdown](https://img.shields.io/badge/markdown-%23000000.svg?style=for-the-badge&logo=markdown&logoColor=white)

Lists

A list helps record essential information in order, which can be vital for the reader and makes it easy for people to understand and find information.

Markdown files support three types of lists:

1. Ordered list
2. Unordered list
3. Task list

Ordered list

The first type is an ordered list. To create an ordered list, start with numbers followed by periods.

1. one
2. two
3. three
4. four

Unordered list

The second type is an unordered list. To create an unordered list, use -, + or * (depending on your preference - they'll all render as an unordered list):

* First item
* Second item
* Third item
* Fourth item


- First item
- Second item
- Third item
- Fourth item

+ First item
+ Second item
+ Third item
+ Fourth item

Task list

The third type is a task list. To create a task list, list items start with a hyphen, followed by a space, followed by square brackets []. You can use an x in the bracket [x] to mark a task as complete.

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] Add delight to the experience when all tasks are complete :tada:

Mentioning people and teams

Mentioning users and teams in markdown

To mention a person or team in a GitHub markdown file, type @ and write the username or team username.

## person or individual username

@officialrajdeepsingh, check out the following change.

## Team or company
The section blog theme is maintained by @frontendweb

Referencing issues and pull requests

Issues and pull requests

To mention issues and pull requests in a GitHub markdown file, type a #, then type the issue or pull request number or title. Then press either tab or enter to complete the highlighted result.

Remove the default _target blank in logo #93

Using emoji

Adding emoji in markdown.

To add an emoji to your writing, type the emoji's code between two colons. If you just type :, a list of suggested emojis on GitHub will appear.

Once you find the emoji you're looking for, press Tab or Enter to choose the highlighted result.

Don't forget to leave a star on our repository! :star:

Footnotes

To add a footnote reference, add a caret and an identifier inside brackets ([^1]) using the following syntax:

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

Alerts

Alerts are a Markdown extension based on the block quote syntax that you can use to emphasize important information.

GitHub Flavored Markdown supports five types of alerts: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION]. You can use any of them:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

The Alert syntax looks like this in the browser:

Adding alert example in markdown.

Advanced Formatting Syntax

This advanced formatting syntax section contains advanced use cases, such as adding diagrams and tables, collapsed sections, mathematical expressions, and more.

1. Creating a table
2. Creating a collapsed section
3. Creating diagrams
4. Mathematical expressions

Creating a table

To create tables in Markdown, you can use pipes | and hyphens -. Hyphens are used to create a column's header, while pipes are used to separate columns.

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

The table looks like this in the browser:

Table example in markdown.

Creating a collapsed section

To create a collapsed section in a markdown file, you can use the <details> tag. This tag is an HTML element that you can easily use to extend the functionality of GitHub Flavored Markdown. Here's how it works:

<details>
  <summary>Click to here. </summary>

   ### You can add a message here

   You can add text within a collapsed section. 

   You can add an image or a code block, too.

   ```ruby
     puts "Hello World"

The collapsed syntax looks like this in the browser:

![Collapsed example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/Collapsed-in-markdown.png)
_Collapsed example in markdown._

### Creating diagrams

To add diagrams to a Markdown file, use triple backticks and wrap them inside quadruple backticks. Then, tell which identifier (Mermaid, GeoJSON, TopJSON, ASCII STL) you used for the diagram.

GitHub supports diagrams using four syntaxes: mermaid, geoJSON, topoJSON, and ASCII STL.

1. [Mermaid](#heading-mermaid) 
2. [GeoJSON and TopoJSON](#heading-geojson-and-topojson)
3. [ASCII STL](#heading-ascii-stl)

#### Mermaid 

[Mermaid](https://mermaid.js.org) is a Markdown-inspired tool that renders text into diagrams. You can create flow charts, sequence diagrams, pie charts, and more with Mermaid.

The GitHub-flavored Markdown has extended the functionality of using Mermaid with Markdown.

You can create flow charts, sequence diagrams, pie charts, and so on inside Markdown. GitHub handles the rest of that. So how do you render diagrams on the screen?

```markdown
```mermaid
graph LR;
   A --  and --> B -- to --> C

The mermaid syntax looks like this in the browser.

![Mermaid example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/mermaid-degram.png)
_Mermaid example in markdown._

#### GeoJSON and TopoJSON

You can use [GeoJSON](https://geojson.org/) or [TopoJSON](https://github.com/topojson/topojson) to add an interactive map to a GitHub repository in a README file or GitHub Wiki.

You can use code block syntax to add an interactive map.

1. GeoJSON can create a map by specifying coordinates. To add an interactive map, use the following syntax:  ` ```geojson  your code ``` `
2. TopoJSON can create a map by specifying coordinates and shapes. To add an interactive map, use the following syntax: ` ```topojson  your code ``` `

**Example using GeoJSON:**

```markdown
```geojson
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1,
      "properties": {
        "ID": 0
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
              [-90,35],
              [-90,30],
              [-85,30],
              [-85,35],
              [-90,35]
          ]
        ]
      }
    }
  ]
}

**Example of TopJSON:**

```markdown
```topojson
{
  "type": "Topology",
  "transform": {
    "scale": [0.0005000500050005, 0.00010001000100010001],
    "translate": [100, 0]
  },
  "objects": {
    "example": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Point",
          "properties": {"prop0": "value0"},
          "coordinates": [4000, 5000]
        },
        {
          "type": "LineString",
          "properties": {"prop0": "value0", "prop1": 0},
          "arcs": [0]
        },
        {
          "type": "Polygon",
          "properties": {"prop0": "value0",
            "prop1": {"this": "that"}
          },
          "arcs": [[1]]
        }
      ]
    }
  },
  "arcs": [[[4000, 0], [1999, 9999], [2000, -9999], [2000, 9999]],[[0, 0], [0, 9999], [2000, 0], [0, -9999], [-2000, 0]]]
}

### ASCII STL

GitHub Flavored Markdown supports STL syntax. STL syntax allows you to add interactive 3D models in markdown. You can use the following syntax: ` ```stl your code.``` `

```markdown
```stl
solid cube_corner
  facet normal 0.0 -1.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 1.0 0.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
  facet normal 0.0 0.0 -1.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 1.0 0.0 0.0
    endloop
  endfacet
  facet normal -1.0 0.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 0.0 1.0
      vertex 0.0 1.0 0.0
    endloop
  endfacet
  facet normal 0.577 0.577 0.577
    outer loop
      vertex 1.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
endsolid

The STL syntax looks like this in the browser:

![STL example in markdown.](https://www.freecodecamp.org/news/content/images/2024/04/stl-example.png)
_STL example in markdown._

### Mathematical expressions

You can add mathematical expressions, such as equations, terms, formulas, and so on, to a GitHub markdown file. GitHub uses [LaTeX](https://www.cmor-faculty.rice.edu/~heinken/latex/symbols.pdf) formatted within Markdown. There are two ways to add these expressions:

1. Writing inline math expressions
2. Writing math expressions as code blocks

#### Writing inline math expressions

An inline math expression starts with `$` and ends with `$`. 

```markdown
Inline math expression example: $\sqrt{3x-1}+(1+x)^2$

The inline math syntax looks like this in the browser:

Inline math expression example

Writing math expressions as code blocks

To add a math expression's code block to the Markdown file, use the ```math code block and wrap it inside ``` backticks to display the expression as a block.

To add a math expression's code block to the Markdown file, use the ````math code block and wrap it inside triple backticks to display the expression as a block.

```math
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)

```

The math code block syntax looks like this in the browser:

Code block math expression example

Conclusion

Markdown syntax works well in GitHub and all other central Git servers, such as GitLab, Gitea, and so on.

Different tools name their markdown differently. For example, GitHub extends markdown functionality in its own way and builds GitHub Flavored Markdown. GitLab also extends markdown functionality and builds and creates a GitLab-flavored markdown.

Markdown syntax is mostly the same in every Git service. But alerts, diagrams, and a few other features only work in GitHub Flavored Markdown.

Reference

• GitHub docs – quickstart for writing on GitHub
• GitHub docs – basic syntax
• Tutorial about rendering STL in Markdown on GitHub

Neovim can be a bit problematic to start with, especially for newcomers. Writing a Neovim configuration from scratch is often difficult. To resolve this issue, we will install Neovim using the Nvchad framework.

Nvchad is a Neovim framework/configuration provider that has a rich, beautiful UI interface, blazing-fast startup time, and helps you work productively with Neovim.

You don't need to configure everything from scratch, as most things come pre-configured. There are multiple themes, code snippets, syntax highlighting, LSP configuration, plugin management, key mapping, and other helpful features.

In this article, I'll give you step-by-step instructions on installing Neovim and nvchad from scratch in your Linux and Debian based distro.

How to Set Up the Project

To download Neovim and nvchad in your distro, you'll need some additional command line tools. These will help you install the software:

1. Git CLI
2. Curl CLI
3. Unzip CLI
4. Fc cache (Font Config) CLI

Let's go through installing these tools to make sure you have them:

Install the Git CLI

To install Git, run the following command:

sudo apt-get install git

Install the Curl CLI

To install curl, run the following command:

sudo apt-get install curl

Install the Unzip CLI

To install Unzip, run the following command:

sudo apt-get install unzip

Install the Fc cache (Font Config) CLI

To install the Fc cache CLI, run the following command.

sudo apt install fontconfig

How to Install Neovim and nvchad

If you follow these steps, you can easily install Neovim and nvchad, even if you are a newcomer. It takes some time, but you don't need to have deep knowledge about Neovim and nvchad to get them set up.

Install Neovim

The first step is to install Neovim on your machine. To do that, you'll need to run the following command depending on your distro:

# Ubuntu ( Snap User)
sudo snap install nvim --classic

# NixOS
nix-env -iA nixpkgs.neovim

# MacOS
brew install neovim

# Arch Linux
sudo pacman -S neovim

For other operating systems such as Windows, you can read the installation documentation Page. I've also written an article on the correct way to install Neovim, which you can also check out.

How to Install Nerd Font

The next step is to install Nerd Font on your laptop or operating system. Nerd Font is a prerequisite for nvchad. If you cannot download Nerd Font, your nvchad UI will not work.

To install Nerd Font in Debian or Debian-based distros and macOS, you can run the following command:

# Debain, Ubuntu, Linux Mint, Kali Linux, etc.
bash -c  "$(curl -fsSL https://raw.githubusercontent.com/officialrajdeepsingh/nerd-fonts-installer/main/install.sh)" 

# MacOS
brew tap homebrew/cask-fonts && brew install --cask font-<Nerd-FONT- NAME>-nerd-font

Before running the nerd-fonts-installer, make sure you've installed curl, unzip, and Fc cache CLI in your Debian distro, following the instructions above.

How to Install nvchad

The last and final step is to install the nvchad framework in Neovim. To do so, run the following command:

# Linux & macOS
git clone https://github.com/NvChad/starter ~/.config/nvim && nvim

The following command takes some time, depending on your internet speed, and installs additional plugins required by nvchad from the internet.

Conclusion

For a newcomer starting with Neovim, the nvchad framework is a great choice. Without nvchad, configuring Neovim from scratch is a hard task for a beginner. Choosing the Neovim framework (configuration) is the right choice for newcomers.

Before starting with Neovim, read up and make sure It is the right choice for you. I recently found a VS Code plugin created and maintained by Neovim. You can get the same Neovim experience inside VS Code. After that, you can decide which you prefer.

With one click, you can publish your production-ready code or package on npm, GitHub pages, docker images, deploy your production code on a cloud provider, and so on.

The problem starts when you're testing GitHub Actions. It can be time-consuming and painful. First, you have to change the GitHub Actions file locally, push your local code into your GitHub repository, and wait for the result.

To solve this issue, You can use the act CLI tool to test and write the GitHub action locally. With act CLI, you do not need to commit/push your local code to the GitHub Repository. You test GitHub action locally on your laptop or machine.

Here are the steps involved:

• How to install act.
• How to configure and initialize the act CLI.
• How to use the act CLI tool.

How to Install act for GitHub Actions

The act CLI tool works with Docker. Before starting with act CLI, First, install Docker on your system or laptop.

To install the act CLI, you need to run the following command:

# Window
choco install act-cli

# MacOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

How to Configure and Initialize the act CLI

After the act CLI installation is successful on your laptop or machine, the next step is to run it in your project.

act CLI asks which Docker image size—large, medium, or micro—must be installed during installation.

There are various Docker image sizes:

1. The Docker Micro image size is 200 MB, and small projects use it.
2. The Docker Medium image size is 500 MB, and Big Project uses it.
3. The Docker Large image size is 17 GB, and Enterprise uses it.

The act CLI uses the Docker image to run the GitHub action locally.

$ act

The command output in the terminal looks like this:

$ test-github-actions git:(main) ✗ act
? Please choose the default image you want to use with act:
  - Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
  - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
  - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

Default image and other options can be changed manually in ~/.actrc (please refer to https://github.com/nektos/act#configuration for additional information about file structure) Micro
[Build Ghost and test theme/install] 🚀  Start image=node:16-buster-slim
INFO[0023] Parallel tasks (0) below minimum, setting to 1 
[Build Ghost and test theme/install]   🐳  docker pull image=node:16-buster-slim platform= username= forcePull=true
INFO[0031] Parallel tasks (0) below minimum, setting to 1 
[Build Ghost and test theme/install]   🐳  docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Build Ghost and test theme/install]   🐳  docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Build Ghost and test theme/install]   ☁  git clone 'https://github.com/vimtor/action-zip' # ref=v1.2
[Build Ghost and test theme/install]   ☁  git clone 'https://github.com/softprops/action-gh-release' # ref=v0.1.15
[Build Ghost and test theme/install] ⭐ Run Main actions/checkout@v4
[Build Ghost and test theme/install]   🐳  docker cp src=/home/officialrajdeepsingh/medium/test-github-actions/. dst=/home/officialrajdeepsingh/medium/test-github-actions
[Build Ghost and test theme/install]   ✅  Success - Main actions/checkout@v4
[Build Ghost and test theme/install] ⭐ Run Main Easy Zip Files
[Build Ghost and test theme/install]   🐳  docker cp src=/home/officialrajdeepsingh/.cache/act/vimtor-action-zip@v1.2/ dst=/var/run/act/actions/vimtor-action-zip@v1.2/
[Build Ghost and test theme/install]   🐳  docker exec cmd=[node /var/run/act/actions/vimtor-action-zip@v1.2/dist/index.js] user= workdir=
| Ready to zip "build/ home.txt" into example.zip
|   - build/
|   - home.txt
| 
| Zipped file example.zip successfully
[Build Ghost and test theme/install]   ✅  Success - Main Easy Zip Files
[Build Ghost and test theme/install] Cleaning up container for job install
[Build Ghost and test theme/install] 🏁  Job succeeded

After downloading the image from the Docker repository, the act CLI runs the GitHub action.

act CLI generates the ~/.actrc file in the laptop for configuration. The ~/.actrc file contains the Docker image name.

# .actrc
-P ubuntu-latest=node:16-buster-slim
-P ubuntu-22.04=node:16-bullseye-slim
-P ubuntu-20.04=node:16-buster-slim
-P ubuntu-18.04=node:16-buster-slim

To install other Docker images, remove the ~/.actrc file and re-run the act CLI to install the different Docker images.

Error

Due to dependence on Docker, we may face some errors when initializing an act CLI for the first time.

$ act

The error should look like this:

$ test-github-actions git:(main) ✗ act       
ERRO[0000] daemon Docker Engine socket not found and containerDaemonSocket option was not set 
? Please choose the default image you want to use with act:
  - Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
  - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
  - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

Default image and other options can be changed manually in ~/.actrc (please refer to https://github.com/nektos/act#configuration for additional information about file structure) Micro
[Build Ghost and test theme/install] 🚀  Start image=node:16-buster-slim
INFO[0305] Parallel tasks (0) below minimum, setting to 1 
[Build Ghost and test theme/install]   🐳  docker pull image=node:16-buster-slim platform= username= forcePull=true
Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

You're seeing the Cannot connect to the Docker daemon error in the above code. This issue occurs due to the Docker daemon. In simple words, the Docker daemon is not running. You can resolve this issue by starting your Docker and re-running your act command.

There are two ways to run Docker services.

1. Open Docker desktop in your window, and your Docker service is started.
2. Run Docker with the systemctl start docker command on Linux.

You can verify whether your Docker is running or not with the following command:

$ systemctl status docker

● docker.service - Docker Application Container Engine
     Loaded: loaded (/etc/systemd/system/docker.service; enabled; preset: enabled)
    Drop-In: /nix/store/fibzdkfv6in4xw39rm0c7bq4nadzisas-system-units/docker.service.d
             └─overrides.conf
     Active: active (running) since Mon 2024-02-26 12:38:37 IST; 3h 39min ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 1186 (dockerd)
         IP: 0B in, 0B out
         IO: 109.0M read, 152.0K written
      Tasks: 40
     Memory: 148.5M
        CPU: 1min 40.817s
     CGroup: /system.slice/docker.service
             ├─1186 /nix/store/7pzis8dkhs461kl1bg2fp0202dw6r5i5-moby-24.0.5/libexec/docker/dockerd --config-file=/nix/store/3rlv5f0zldcc120b01szywidl0qz9x4p-daemon.json
             └─1256 containerd --config /var/run/docker/containerd/containerd.toml

Feb 26 12:38:37 nixos dockerd[1256]: time="2024-02-26T12:38:37.532987858+05:30" level=info msg="containerd successfully booted in 0.016901s"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.562515048+05:30" level=info msg="[graphdriver] using prior storage driver: overlay2"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.564062690+05:30" level=info msg="Loading containers: start."
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.778478313+05:30" level=info msg="Default bridge (docker0) is assigned with an IP address 172.17.0.0/16. Daemon option --bip can be used to set a preferred IP address"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.805931545+05:30" level=info msg="Loading containers: done."
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.828589904+05:30" level=info msg="Docker daemon" commit=v24.0.5 graphdriver=overlay2 version=24.0.5
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.828929197+05:30" level=info msg="Daemon has completed initialization"
Feb 26 12:38:37 nixos systemd[1]: Started Docker Application Container Engine.
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.841992729+05:30" level=info msg="API listen on /run/docker.sock"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.841993669+05:30" level=info msg="API listen on /run/docker.sock"

How to Use the act CLI Tool

act CLI has many options, but we'll look at some important ones. You can check all the options by running the act --help command.

act CLI Options

Here are some act CLI options:

• Events
• Lists
• Running Specific Jobs
• Graph
• Environment Variables
• Secrets

Events

act CLI's default action is the push action, which triggers only push events by default.

$ act

You can change the event after passing the second argument, which is the name of your action. In our case, we'll pass pull_request.

$ act pull_request

There is a long list available to trigger workflows. You can read it on the GitHub action documentation.

Lists

The list option prints all the available jobs that you write in .github/workflows.

$ act -l

The command output in the terminal looks like this.

$ act -l    
Stage  Job ID             Job name           Workflow name                  Workflow file      Events      
0      zip                zip                Convert files into Zip         build-project.yml  release     
0      request_test       request_test       Pull Request                   fork.yml           fork        
0      pull_request_test  pull_request_test  Pull Request                   issues.yml         issues      
0      show               show               Convert files into Zip folder  test.yml           pull_request

Running Specific Jobs

You use the --job option command to run specific jobs from your workflows.

Make sure your job name is unique – otherwise, it runs all jobs containing the same in your workflow. Whenever you can not pass an event by default, trigger the push event.

Syntax

act --job <name-of-your-job>

For example, we run a specific show job.

$ act --job 'show'

Graph

The graph option draws the available workflow jobs structure in your terminal as a graph.

$ act --graph

The command output in the terminal looks like this:

$ act --graph
 ╭─────╮ ╭──────────────╮ ╭───────────────────╮ ╭──────╮
 │ zip │ │ request_test │ │ pull_request_test │ │ show │
 ╰─────╯ ╰──────────────╯ ╰───────────────────╯ ╰──────╯

Environment Variables

Using environment variables with the act CLI is easy. You only need to create a new .env file. act CLI automatically loads the environment that is available in the .env file. For example, we add a ENV_ID variables.

# .env

ENV_ID='My Env'

To use the ENV_ID environment variables, use the following syntax ${{ env.ENV_ID }} in your GitHub action:

# .github/workflows/test.yml

name: Convert files into Zip folder

on: pull_request

jobs:
  show:
    runs-on: ubuntu-latest
    steps:
      - name: Show Env
        run: echo "Env ${{ env.ENV_ID }}"

With the --env-file option, you can change the default .env file name to my-custom.env file.

$ act --env-file=my-custom.env

Secrets

You must create a new .secrets file to load the environment secrets with the act CLI. This automatically loads the environment secrets that are available in the secrets file. For example, we add a APP_SECRET and APP_ID variables.

APP_SECRET='7824jurd789gyu45esxgfgf48822166974gtredsyujn'
APP_ID='7878974561587'

To use the APP_SECRET environment variables, use the following syntax ${{ secrets.APP_SECRE}} in your GitHub action:

# .github/workflows/test.yml

name: Learn environment secrets 

on: pull_request

jobs:
  show:
    runs-on: ubuntu-latest
    steps:
      - name: Show env
        run: echo "App SECRET ${{ secrets.APP_SECRET }}"
      - name: Show varibale
        run: echo "App ID ${{ secrets.APP_ID }}"

You can load your custom my-custom.secrets file containing all your secrets with the --secret-file option.

$ act --secret-file=my-custom.secrets

Conclusion

act CLI helps save time and energy when working and testing GitHub locally. Currently, there is no alternative to act CLI, which allows us to run GitHub actions locally.

act CLI isn't fully compatible with GitHub actions. Some features are not implemented, for example, concurrency, no vars context, incomplete github context, and so on.

You can hire me as a freelance developer with Upwork and other updates. Follow me on Twitter (X) and Medium.

In this article, I'll discuss some of my favourite libraries you can use for building your documentation site.

And don't worry if you don't have that much experience creating documentation yet. Whether you've built a simple documentation site for a small startup or personal project or a vast and complex site for a large company, these libraries will be helpful to you.

Tips for Writing Good Documentation

Before we get into the libraries themselves, though, there are some critical points you'll want to keep in mind when you're building your documentation sites.

Make sure your documentation is clean and easily recognizable.

Ensure your documentation folder is separate in the mono repo, even if you use a poly repo or separate repository.

This separate repository should contain only the markdown and mdx files. This will help your contributors easily be able to recognize which folder is for documentation.

A great example of clean documentation is Next.js, which has a separate folder for documentation, as you can see below:

Nextjs documentation is easily recognizable in the mono repo and contains only the Markdown.

Provide clear guidelines in your documentation.

To improve documentation quality, you should write clear guidelines for technical writers. For example,

1. what front matter is required in the file markdown?
2. Which spelling conventions are correct – for example, do you accept javascript (all lowercase) or JavaScript (with the proper casing)? Or both?
3. Which commands are needed for formatting and linting before applying a pull request?

A pro tip for documentation sites is mentioning additional resources, such as tutorials, courses, and article links for new contributors.

The best examples of clear guidelines are Next.js and the Awesome Repository. Both have clear guidelines for documentation.

Nextjs has clear guidelines for documentation.

Make it easy to contribute.

When contributors want to help out with your project, many of them just want to focus on writing. Most technical writers or documentation contributors do not have time to install and set up your project locally.

Many online IDEs are available these days, and more are coming, such as GitHub Dev, VS Code Dev, Code Sandbox, and GitLab.

Nowadays, many developers and contributors update the documentation file using GitHub's inbuilt IDE or other online IDEs and create pull requests without installing your repository locally.

So, you should at least configure your project to work with one of the online IDEs. It helps to save time and improves the productivity of the technical writer and contributor.

Helpful Documentation Libraries:

1. Nextra
2. Docusaurus
3. Lume
4. Docsify.js
5. Markdoc
6. Content layer
7. Git book
8. Outstatic CMS
9. Code doc
10. Frontmatter

Nextra

Nextra

Nextra is an open-source, simple, powerful, and flexible site generation framework built on Nextjs. Nextra was created by developers at Vercel.

Nextra helps manage your content with MDX. With Nextra, you can build both small and large-scale documentation websites.

Nextra comes with various built-in features, such as:

1. Organizing content with file-system routing.
2. Theme Toggling (Light to Dark theme)
3. Inbuilt search
4. Multiple layouts
5. Syntax highlighting
6. Multiple languages (Internationalized)
7. Custom themes

Nextra also helps to save you time and energy, as you can directly work on your documentation without writing a single line of code. You also do not have to maintain the code base. This lets you focus on documentation writing.

Cons

1. There are fewer customizations you can make with Nextra
2. Nextra comes with more limited features

To learn more about Nextra, you can check out the tutorial I wrote about it.

Docusaurus

docusaurus

Docusaurus is an open-source static-site generator built and maintained by the Meta team. Docusaurus helps you write and manage your large and small documentation and blog websites.

Docusaurus comes with various built-in features, such as:

1. It's easy to configure
2. You can customize your site's layout, design, and features with React components
3. You can write content in Markdown and MDX.
4. It handles localization well
5. You can manage versioning
6. It has a built-in plugins ecosystem
7. You can customize and change themes
8. There's good client API support
9. It has TypeScript and JSDoc support
10. You can create both a blog and a documentation website with Docusaurus.

Docusaurus is a well-established library used by many companies. And one of the best parts about Docusaurus is that it has a more significant number of active contributors, so the tool is well-maintained.

Cons

1. Customizing and managing a large documentation website with Docusaurus can be tricky because of complex Docusaurus configuration options.
2. Configuring Docusaurus blog plugins can be a massive headache because of the configuration. Lastly, Docusaurus can not support categories for articles.
3. Docusaurus does not come with search functionality. To enable search functionality, you have to depend on a third-party service. Confirming the third-party search functionality is sometimes not an easy task.

Lume

lume

Lume is a fast and flexible open-source static site generator based on Deno. You can build documentation sites, a portfolio, a company website, or a blog with Lume.

Lume comes with various built-in features, such as:

1. Processors
2. Plugins support
3. Multiple file formats, like markdown, yaml, JavaScript, typescript, jsx and nunjucks, and it's easy to extend with other features.
4. Inbuilt search and pagination support
5. It supports multiple template engines (JSX, Preact, MDX, Remark, and so on)
6. Ability to create relationships between two pages

You can customize so many things with Lume that you may not even be able to imagine until you try it out.

Cons

1. Starting with Lume is not an easy task. It's a steeper learning curve, and it may take some time to get enough experience to use it effectively – so Lume is not the best for beginners.
2. You need a third-party service to enable search functionality on your website.
3. Since there's so much customization possible, sometimes you might get confused about what you've chosen.

Still, Lume gives you more control and power over your documentation site, so if you're willing to take the time to learn it, I think you'll enjoy it. You can read my in-depth tutorial on freeCodeCamp to learn more about Lume.

Docsify.js

Docsify.js

Docsify is an open-source, simple, and lightweight documentation generator. It's heaven for developers with a C, Rust, and C++ background. You can start using Docsify without having any knowledge of JavaScript or React.js.

Docsify comes with a number of built-in features, such as:

1. It's simple and lightweight
2. It's easy to customize and configure
3. You can extend Docsify's functionally with built-in plugin API
4. It has multiple themes support
5. There's emoji support
6. It supports server-side rendering

In Docsify, you can focus on writing documentation without worrying about maintaining the codebase.

You can start your documentation site within minutes. You can deploy the Docsify website with one click on GitHub pages.

The most important thing about Docsify is that you don't need prior knowledge to work with Docsify or any other tools or configuration.

Cons

1. Docsify comes with fewer features, but customization options are available.
2. Docsify only has a few themes and plugins available on the internet.
3. Most of the themes you find on the internet are outdated in terms of their UI.

To learn more about Docsify, read my in-depth tutorial on freeCodeCamp.

Markdoc

Mark doc

Markdoc is an open-source, powerful, and flexible Markdown-based framework. Markdoc is built and maintained by the Stripe team. With Markdoc, you can develop your personal blogs and documentation sites.

Markdoc comes with several built-in features, such as:

1. It's lightweight
2. There's built-in syntax validation
3. It has support for partials
4. You can extend Markdoc with custom functions
5. It supports tags
6. You can customize styles with annotations
7. It supports variables and attributes

Markdoc is developer and writer-friendly. You can build interactive documentation and static content sites using pure HTML, Next.js, and React.js.

Cons

1. To work with makdoc, you must write the entire website code from scratch.
2. Markdoc is not for beginner developers. You must know some advanced JavaScript and React concepts when working with Markdoc.

Contentlayer

Content layer

Contentlayer is an open-source content SDK that validates and transforms your content into type-safe JSON data so you can easily use it with your existing frameworks, such as Next.js.

The best part about Contentlayer is that you can build a type-safe schema for your blog and documentation.

Contentlayer works similarly to Markdoc – you must write the documentation and maintain the code base.

There are many helpful features, but here are a few:

1. It's framework agnostic
2. It's built to be very fast
3. Makes it easier to parse content on your site
4. You can use JavaScript/TypeScript – no new query language required
5. It has automatic content and frontmatter validation

Cons

1. Contentlayer comes with support for a limited number of frameworks.
2. You must write website code from scratch to work with the Content layer.

Read my in-depth tutorial on Medium to learn more about Contentlayer.

Gitbook

Git book

Gitbook is not open-source, but it comes with free and paid plans. Gitbook is built and designed to manage documentation. You can even develop your API and service documentation website with Gitbook.

Git Book comes with various built-in features, such as:

1. It has a no-code solution
2. You can easily integrate it with other applications
3. You can customize and change the theme with one click
4. It's easy to use it to collaborate with your team
5. It has a powerful block-based editor
6. You can embed code your demo code with code sandbox IDE
7. It has built-in search support
8. It has built-in SEO, sitemap and caching & CDN support

Gitbook comes with a no-code solution – you do need to write a single line of code to create a documentation site. Gitbook provides you with a modern feel for creating documentation without writing code.

You can integrate Gitbook with other services like GitHub. And you do not need to worry about deploying Gitbook – it does all the hard work for you. With one click, you can focus on writing and designing or changing themes in your documentation in Gitbook.

Cons

1. Many features like theme customization and team management come with the paid plan.

Outstatic CMS

Outstatic CMS

Outstatic CMS is a Next.js-based open-source static CMS that helps you manage your content with the help of GitHub.

Outstatic cms comes with several built-in features, such as:

1. There's an AI completion option
2. You can manage your content with custom fields
3. It's quick and easy to setup
4. You don't need a database
5. It's a modern content editor

Using Outstatic CMS, you can easily publish, update, and remove the content using the dashboard and editor. This is helpful if you don't know how to use Markdown and some who depend on grammar tools, for example, Grammarly, Turnitin, Quillbot, and so on.

Outstatic CMS only works with Next.js and GitHub. Outstatic directly creates content inside your GitHub repository using Github API.

Cons

1. You need to write website code design to build and test from scratch.
2. Outstatic CMS does not work offline.

Read my in-depth tutorial on Medium to learn more about it.

Code doc

Code Doc

Code Doc is an open-source, simple, lightweight, easy-to-configure documentation generator tool that helps create beautiful and modern software documentation websites within minutes.

Code Doc comes with several built-in features, such as:

1. It's simple and lightweight
2. It's easy to customize and configure
3. It has an enhanced markdown and code block experience
4. It has integrated search and dark mode
5. You can extend the functionality with the Code doc Plugin API
6. You can build your own custom components

With code doc, you focus on your documentation writing rather than writing and maintaining your codebase. But Code Doc is easy to customize and configure. You do not need prior knowledge to use it.

The most important thing about Code Doc is that it has more modern UI features than Docsify.

Cons

1. A Code Doc project or repository cannot be actively maintained by its developer.

Front Matter

Front Matter CMS

Front Matter is a Headless CMS right in your Visual Studio Code. Front matter gives a helping hand to technical writers and coders.

Front Matter cms comes with several built-in features, such as:

1. It works seamlessly with any static site generator
2. It's fully configurable
3. It brings the features/benefits of a CMS to your VS Code
4. You get a full site/page preview within VS Code
5. You can manage your content, media, snippets, and data with VS Code
6. You can edit your metadata
7. You can check your SEO status in VS Code

The tool works inside VS Code, letting you edit, write, update, and delete documentation in your VS Code without ever having to leave the editor. You can write your documentation using Markdown and VS Code.

You can also edit your metadata (front matter like title, description, tag, date, and so on) and check the SEO status in VS Code.

The best part is integrating Front Matter with other tools or libraries, such as Nextra, Docusaurus, Lume, and Docsify, to enhance the developer's writing experience using VS Code.

Cons

1. You cannot use Front Matter CMS with other IDEs like Vim, Neovim, Atom, Sublime Text, JetBrains IDEs, and so on.
2. Front Matter CMS is not useful for everyone. Front matter CMS Only targets software developers who will find it very useful.

Read my in-depth tutorial on Medium to learn more about the Front Matter CMS.

Conclusion

Without documentation, your product or service will never be successful. Spend equal time on one code base and as well on documentation.

For quick and short-term documentation, I recommended Git Book, nextra, and Docusaurus. If you have time and teams, go with Outstatic CMS, Content layer, and Mark doc. Lastly, you do not know JavaScript and reactjs. You can go with Git Book and Docsify.

I am not recommending the Code Doc library due to inactive maintenance by its developer. I'm not sure if the code doc was abandoned by its developer or not.

You can hire me as a freelance developer with Upwork and other updates. Follow me on Twitter (X) and Medium.

Creating a documentation site can be challenging, especially if you're not familiar with front-end development.

I have been a front-end developer for the past 8 years. During that time, I have used many frameworks to build documentation, like Next.js, nextra, content layer, Ghost CMS, lume (deno), docusaurus, and Mark doc.

But to use many of these, you need to have essential knowledge about JavaScript, Next.js, and React. You may run into some challenges, like:

1. Lack of knowledge of JavaScript, React, or other necessary tools
2. Documentation versioning
3. Configuration
4. Deployment

In this guide, I'll introduce you to a powerful tool that can help you write documentation without needing as much technical knowledge.

What is Docsify?

To help you solve this problem, I'd recommend a tool called docsify. Docsify is a simple and lightweight documentation generator. You can start using it without having any knowledge of JavaScript or React.

Docsify comes with zero configuration, no statically built HTML files, multiple theme support, inbuilt plugin API, and full-text search support with a plugin. It also deploys on a wide range of platforms like GitHub pages, GitLab Pages, Firebase Netlify, Vercel, and others.

I created a demo project to show you how to use it – the source code is available on GitHub. You can also check out the live demo site.

How to Setup and Use Docsify

You can create a new project with the docsify-cli. To use docsify-cli, you need to install Node and NPM if you don't already have them installed.

npm install -g docsify-cli
# or
yarn add -g docsify-cli
# or
pnpm add -g docsify-cli

The command output looks like this:

❯ pnpm add -g docsify-cli

Packages: +198
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 199, reused 114, downloaded 84, added 198, done
.pnpm/docsify@4.13.1/node_modules/docsify: Running postinstall script, done in 196ms

/home/rajdeepsingh/.local/share/pnpm/global/5:
+ docsify-cli 4.4.4
+ pnpm 8.7.0

Done in 13.9s

Create your new project with the docsify-cli init option.

➜ docsify init docs

Initialization succeeded! Please run docsify serve ./docs

You can also specify the --theme and --plugins.

➜ docsify init docs --theme buble --plugins

You can read more about docsify-cli on the documentation page.

Install the plugins with the docsify init option.

Next, start your local development server using docsify-cli. For that, run the following command:

docsify serve docs
# or
docsify serve .

Your local server runs on a 3000 port locally.

Run docsify serve

Your website should look like this when you open it in the browser:

Demo Doctify

Docsify Folder Structure

Docsify has a straightforward folder structure. By default, when you create a new project with docsify-cli, there are three main files:

├── index.html // This is an HTML entry file.
├── .nojekyll  // This is helpful when you deploy your project on GitHub pages.
└── README.md  // This is the home page or / router

How to Customize Docsify

Docsify comes with lots of customization options, and you don't need any additional knowledge to configure it – it's pretty straightforward, just like copying and pasting code.

In this guide, we'll explore some of the most common customization options. For advance configuration, you can check out the Docsify documentation.

1. Basic configuration
2. Loading screen
3. Sidebar
4. Header
5. Cover Page
6. Plugins
7. Themes
8. Deployment

Basic configuration

In the basic configuration, you can change or add a logo, a name, add your GitHub repository link, a theme color, and so on.

Here's the code to do that – you can fill in your own details.

 <!-- index.html -->
 <script>
      window.$docsify = {
        logo: '/_media/icon.svg',  <!-- add logo -->
        name: "Document",  <!-- Website name it appears in sidebar. -->
        nameLink: '/',  <!-- url for name -->
        repo: "officialrajdeepsingh/docsifyjs",<!--github repository-->
        maxLevel: 2,  <!-- Maximum Table of content level. -->
        themeColor: '#3F51B5', <!-- Customize theme color -->
      };
</script>

Loading screen

Enabling a loading screen or dialogue is typically very tricky, especially if you come from the JavaScript and React.js ecosystem.

Loading screen in Docsify

In Docsify, you can enable a loading screen without any configuration. You just simply write some text along with an HTML element inside your app ID, which will then show as a loading screen. It looks like this:

<!-- index.html -->
<div id="app">Please wait...</div>

<!-- or -->

<div id="app">
<h1> Please wait... </h1>
</div>

Sidebar

By default, the sidebar shows the table of contents. But you can customize it very easily. First, you'll need to enable the sidebar.

<!-- index.html -->
<script>
   window.$docsify = {

        loadSidebar: true, <!-- Enable sidebar -->

   };
</script>

Then create a new _sidebar.md file at the root level and paste the following code:

- [Home](README.md)
- [Draft Article](draft-article.md)
- [Guide](guide.md)
- [First](page-first.md)
- [Second](page-second.md)
- [Third](page-third.md)
- [Four](page-four.md)

Your sidebar should now look like this:

Your sidebar looks like this.

Header

By default, you won't be able to see the Navbar on your Docsify site:

No Navar

But don't worry, you can change that. To show the Navbar, you first have to enable it like this:

<!-- index.html -->
    <script>
      window.$docsify = {


        loadNavbar: true,     <!-- enable navbar -->

      };
    </script>
  </body>
</html>

Then create a new _navbar.md file at the root level and paste the following code:

* Getting started

  * [Quick start](quickstart.md)
  * [Writing more pages](more-pages.md)
  * [Custom navbar](custom-navbar.md)
  * [Cover page](cover.md)

* Configuration
  * [Configuration](configuration.md)
  * [Themes](themes.md)
  * [Using plugins](plugins.md)
  * [Markdown configuration](markdown.md)
  * [Language highlight](language-highlight.md)

Your Navbar should now look like this:

Customize Navbar in Docsify

Cover Page

First, enable the cover page in docsify with the following code:

<!-- index.html -->
<script>
      window.$docsify = {

        coverpage: true,     <!-- enable coverpage -->

      };
</script>

The next step is to create a new _coverpage.md file.

# Learn Docsify 
### Learn the docsify start from beginner.

[Start Learn]()
[Github](#/README)

Your website cover page should look like this:

Your cover page

The cover page and your UI depend on the theme, so they'll differ from theme to theme.

Plugins

Plugins help provide additional functionality and features to Dicsify and enhance the user experience as well.

You can create and use plugins according to your own requirements. [Docsify](https://github.com/docsifyjs/awesome-docsify) has many plugins available that are open-source and created by various contributors.

You can use any plugin by just copy-pasting the code. Even you can create your own plugins with docsify.

How to use third-party plugins

In this example, we'll enable the search bar functionally with the help of the docsify plugin.

To enable the search bar, copy and paste the following script inside your index.html file:

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

Now the search bar will appear and work on your site. With the search plugin, you can also configure various functionality – read more about it on the search plugin installation and configure page.

Docsify Search plugin

How to create your own plugin with docsify

To create your own plugin in docsify, there's an inbuilt hook you'll need to use for the plugin.

Docsify has six inbuilt hooks: init, mounted, beforeEach, afterEach, doneEach, and ready.

1. init: gets invoked one time when the docsify script is initialized.
2. mounted: gets invoked one time when the docsify instance has mounted on the DOM.
3. beforeEach: gets invoked on each page load before the new markdown is transformed to HTML.
4. afterEach: called on each page load after the markdown has been turned into HTML.
5. doneEach: gets invoked on each page load after new HTML has been appended to the DOM.
6. ready: gets invoked one time after rendering the initial page.

With the help of these hooks, you can create a plugin. To learn more about creating your own plugins, check out the custom plugin document page.

In this example, we'll create an edit button using the beforeEach plugin hook. It shows the EDIT DOCUMENT button on every page.

<!-- index.html -->
    <script>
      window.$docsify = {

        plugins: [

        <!-- write own custom plugin -->
        function editButton(hook, vm) {

          // call the hook
          hook.beforeEach(function (html) {

            var url = "https://github.com/officialrajdeepsingh/docsifyjs/edit/master/" + vm.route.file;

              // basic route fix 
            let tempFile = url.replace("docsifyjs/README.md", "README.md",)
              ? url.replace("docsifyjs/README.md", "README.md")
              : url;

            // Add Edit Button
            var editHtml = "[📝 EDIT DOCUMENT](" + url + ")\n";

            // Add edit button on top of file
            return editHtml + html + "\n----\n" + "Last modified " + editHtml;
          });
        },
        ],


      };
    </script>

Themes

Docsify has both official and community-made themes. You can use any of them, and the good part is you do not need to write any extra code when you switch themes.

<!--vue theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" />

<!-- buble theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" />

<!-- dark theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" />

<!-- pure theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />

You can choose to compress or not compress theme CSS files. The compressed CSS file is a minified version of the theme, and it is a lightweight CSS file for production. Other the other hand, a non-compressed theme CSS file is helpful for development.

You just copy the CSS theme (Vue, bubble, dark, and pure) file and paste it inside the head element. And with that, your theme is changed.

In terms of non-official themes, I think the docsify-themeable theme is the best option for you.

Deployment

Docsify has various options for deployment. You can deploy your Docsify site on GitHub pages, GitLab Pages, Firebase Hosting, VPS (Nginx), Netlify, Vercel, AWS Amplify, and Docker.

In some platforms like GitHub pages, you deploy your docsify site directly with the GitHub repository without writing any configuration.

Here's the process to do that:

You'll go to Settings > Pages > Source > and then select Deploy from a branch > Branch > Select your branch with folder and click on the save button.

Deploy docsify with GitHub pages

It will take some time, depending on your website size. After deployment finishes, you should see your production URL.

Finish the deployment

Conclusion

Docsify is a powerful tool for generating documentation sites. In docsify, you can focus on documentation writing, not UI design.

Docsify is a good option for developers who aren't that familiar with JavaScript. If you focus more on low-level languages like C++ or rust, docsify can help you get started writing your documentation with one command.

I recently used docsify for my awesome-nextjs repository. You can easily deploy on the GitHub page without any configuration.

Just keep in mind that there are two downsides to docsify:

1. Docsify does not generate dynamic SEO meta tags for a page. It only generates a title and description.
2. The docsify theme does not provide a modern UI feel.

But it's still very useful! Enjoy creating your documentation :)

Gnome is an open-source Linux-based distro desktop environment (operating system) maintained by a large number of developers.

Choosing the right Gnome extension(s) can be tricky, and a tad overwhelming. To help you out, in this guide I'll go over six Gnome extensions that most users install, irrespective of their experience with Gnome.

Table of Contents

1. Clipboard History
2. Extension List
3. Freon
4. Net Speed
5. Privacy Quick Settings
6. Dim On Battery Power

Clipboard History

As a developer, you'll often copy and paste stuff, and sometimes it gets messy. In some cases, you might lose what you've copied or copy the wrong text.

The Clipboard History Gnome extension helps you manage or preserve your clipboard history.

Manage your clipboard history.

With this extension, you get your old clipboard (copy-paste) history and you can reuse it as well. The Clipboard History extension comes with many cool features that you can change in the extension settings tab.

For example, you can change the panel width, remove the white space, change the max clipboard history size, and more.

Extension List

Gnome users install many extensions to increase productivity and improve the user experience with the Gnome desktop.

The problem occurs when you install lots of extensions, and managing them can be a difficult task.

Extension List gnome extension

The Extension List extension gives you a list of installed extensions, and you can easily turn them on/off, manage settings, and uninstall extensions.

Freon

All Linux distro systems are power-consuming machines, and you may have information about temperature, fan RPM, and voltage on the home screen. When the temperature is high, actions like closing some running apps or not using the laptop for some time can help to reduce the temperature.

Freon gnome extension

The Freon extension is helpful for Gnome users because it gives you operating system information about the CPU, disk, video card temperature, voltage, and fan RPM on the distro home screen in Gnome.

Net Speed

Internet or connectivity is an important factor for developers. Without the Internet, we cannot work. Sometimes you can't tell if the internet speed is good or bad. For example, in India, network connectivity is a big issue.

Net Speed gnome extension

To solve this issue, the Net Speed Gnome extension is the best. It gives you the current net speed on your desktop home screen.

Privacy Quick Settings

It is important to secure yourself on the internet, especially as a user. Sometimes we forget which access we've enabled on the Gnome desktop, such as locations, microphones, and cameras.

Privacy Quick Settings gnome extension

The Privacy Quick Settings Gnome extension is useful because it gives you a panel or icon on the home screen where you can see which access you've enabled, and you can easily update those privacy settings as needed.

Dim On Battery Power

Just like I do, some developers like to work with full brightness on their PC. I find that it's easier on my eyes.

Sometimes, you may forget to charge your laptop while working, and this may result in the laptop or machine switching off because of a dead battery.

The Dim On Battery Power Gnome extension can help reduce brightness when the machine is running low on battery power, and it gives you a notification that you need to charge the machine so you can easily know when your laptop's battery power is low.

Conclusion

You'll find my extension list useful whether you're a newbie or a pro at using Gnome. It gives you a starting point, and you should easily be able to install all the extensions I mentioned in the list without any problems.

You can share and follow me on Twitter and Linkedin. I write tons of articles related to frontend development and Linux.

If you are interested in those topics, you can follow me on Medium, officialrajdeepsingh.dev, join the frontend web publication and sign up for my free newsletter.

It has many features and an editor that's highly optimized for writing. You can even build different themes using handlebars.js.

But if you don't know Handlebars, learning it can be a long and difficult process. If you are already a Next.js developer and you don't know Handlebars, creating a new theme for your Ghost-based site can be tough.

In the article, I will teach you how to use Ghost CMS as a backend and Next.js as a frontend. I will guide you through everything related to Nextjs 13 app directory and the Ghost CMS API.

Next.js 13 team currently working on the experimental app folder. Next uses file-based routing with the page directory. The new app directory is based on file system routing and provides additional functionality like layouts, error handling, component loading, and server-side and client-side rending out of the box.

All the code is available on GitHub. You can also check out the live demo website.

Table of Contents

1. Why Use Next.js for the Front End and Not a Ghost CMS Theme?
2. Project Requirements
3. How to Set Up Ghost CMS
4. How to Set Up Ghost CMS with the Cloud
5. How to Get the Blog Template
6. How to Set Up Next.js
7. What to know before following this tutorial
8. Folder Structure
9. How to Configure Ghost CMS and Next.js
10. Understanding the Next.js 13 App Folder
11. Demo Data for the Project
12. How to Build the Blog
13. How to Build the Header
14. How to Build the Footer
15. How to Build the Layout
16. How to Build the Homepage
17. How to Build the Reading Page
18. How to Build the Tag Page
19. How to Build the Author Page
20. How to Build Single Pages
21. How to Handle Pagination
22. Next.js SEO
23. How to Enable Search
24. Error Handling
25. How to Rebuild Your Static Site with Webhooks
26. Conclusion

In this article, we cover the basics of Next's experimental app directory. Then I'll teach you how to step up Next and Ghost CMS locally and how to integrate Ghost with Next. Lastly, I'll show you how to consume data from the backend (via theGhost CMS API ) and show it on the site with React.js.

Why Use Next.js for the Front End and Not a Ghost CMS Theme?

There are a few reasons why you might consider using Next as the frontend framework for your blog:

1. Ghost CMS doesn't generate static builds, but Next.js does.
2. You get increased website speed and performance with Next.js and it now provides built-in SEO support and other optimizations. Ghost doesn't have some of these features.
3. For React developers, it is easy to build a new blog with Next (since Next is React-based), and you do not need to learn additional tools.
4. You'll find a few service providers available for Ghost to deploy a Ghost blog with one click. Most of them come with a paid plan while one or two offer a free plan (but these tend to have time and feature limitations). For Next.js, many players are available in the market.

Basically, when it comes to static builds and website performance, Ghost doesn't perform as well in either case. The alternative is to use a frontend platform like Next, React, Angular, or Vue.

I chose Next because it's a highly in-demand and popular React framework, and plenty of tools and libraries are built around it.

Note that the current project is not ready for TypeScript, but I'm working on it. Because of this I disabled TypeScript during build time like this:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    appDir: true,
  },

  typescript: {
    ignoreBuildErrors: false,
  },

}

module.exports = nextConfig

Project Requirements

To follow along with this tutorial, you'll need basic knowledge of the following packages:

1. PNPM is a Node.js package manager similar to npm or yarn (you can use any of them that you prefer).
2. TypeScript helps you write type-safe code in JavaScript, and can also help improve productivity. It is not required, though. You can use JavaScript in your project.
3. React.js is a free and open-source front-end JavaScript library for building user interfaces with class and function components.
4. Next.js 13 (app) is based on React and it provides additional functionality like routing, error handling, and layouts.
5. Ghost CMS API is an open-source content management system (CMS) similar to WordPress. Ghost is specifically designed and built for blogging. In this project, we'll Ghost as the backend and Next as the frontend. For communication between the backend and frontend development, we'll use the Ghost CMS API.
6. Tailwind CSS is an open source CSS-based framework similar to Bootstrap. We'll use Tailwind CSS to design our blog website.

How to Set Up Ghost CMS

The next step is installing Ghost locally, which you can do with one command. First, you need to install ghost-cli globally with pnpm, yarn, or npm.

pnpm add -g ghost-cli@latest

# or

yarn global add ghost-cli@latest

# or

npm install ghost-cli@latest -g

After installing the Ghost CLI, you can create a new Ghost blog project locally with the following command:

ghost install local

After the blog installation is finished, you can start your local development server with the ghost start command and your local development serve on http://localhost:2368/ghost.

Additional Ghost CLI Commands

There are a few additional commands that are helpful when using the Ghost CLI:

• ghost start: start your server.
• ghost stop : stop your running Ghost server.
• ghost help : check the available list of commands.

Note:

Make sure your current installation directory is empty before installation. Currently, you are installing Ghost in development mode. For production, you won't follow the same steps.

How to Set Up Ghost CMS with the Cloud

If you run into any problems with Ghost local installation, or maybe it's too complicated and you do not have enough space on your drive, you can use a tool like digital press or any other cloud service like GCP or AWS, Digital Ocean, and so on.

I like digital press because it comes with a free plan. Other cloud services do not provide that, which is why I suggest it.

How to Get the Blog Template

Creating a new blog from scratch can be tough. In this tutorial, we'll use a pre-build template from the frontend web. All templates have an open-source MIT license, so you can use them, and you don't need to set up everything.

I picked the Open-blog template from the frontend web.

How to Set Up Next.js

Setting up Next is one of the main parts of this tutorial, where you'll spend time and energy coding, debugging, and deploying the site.

Here are the commands to run depending on whether you're using npx, yarn, or pnpm:

npx create-next-app@latest --experimental-app

# or

yarn create next-app --experimental-app

# or

pnpm create next-app --experimental-app

create a new nextjs app.

After completing the installation process, we must install some additional Node packages for the blog.

These Node packages can help you speed up your development process. Make sure to install all the below packages to follow along with this guide:

Node packages to install:

1. pnpm add @tryghost/content-api(required)
2. pnpm add @types/tryghost__content-api (required by TypeScript)
3. pnpm add tailwindcss postcss autoprefixer
4. pnpm add @tailwindcss/typography
5. pnpm add react-icons
6. pnpm add date-fns
7. pnpm add next-themes
8. pnpm add @radix-ui/react-popover

Here's what each of these packages does:

• @tryghost/content-api package is a Ghost JavaScript Client Library for fetching content API data.
• @types/tryghost__content-api package contains type definitions for @tryghost/content-api.
• TailwindCSS, autoprefixer, and PostCSS are packages required for Tailwind CSS.
• @tailwindcss/typography package for handling dynamic typography with Tailwind CSS.
• The next-themes package enables themes like switching from dark to light mode on your site.
• The react-icons package provides lots of SVG icons for the project. This way, you do not need to download them manually.
• @radix-ui/react-popover is part of the Radix UI ecosystem. I choose the Radix popover component for the design of the search component on the site.
• date-fns package helps convert your published_at date into a different date format.

What to Know Before Following This Tutorial

Before building this project, I highly recommend watching some tutorials on YouTube (especially if you're a beginner with Next.js). These will help you understand some basics about the Next.js experimental app folder.

Every video explains the same kind of topic. If you watch each of the four videos, you have a basic idea of how the Next.js app folder works. That will make this advanced tutorial easier to follow.

Vercel

In this tutorial, Lee Robinson covers the basics of routing, dynamic route segments, data fetching, caching, and metadata.

Sakura Dev

Sakura Dev teaches you about the difference between Next.js pages and the app folder and routing with examples.

Tuomo Kankaanpaa

Tuomo Kankaanpaa teaches you about Next app folder routing, layouts, and server components.

Piyush Garg

Piyush Garg compiles all the new Next features and converts them into a small crash course, and builds a demo project.

Now that you're ready to go, let's get into building our blog.

Folder Structure

Our folder structure looks like this for our demo application:

.
├── next.config.js
├── next-env.d.ts
├── package.json
├── pnpm-lock.yaml
├── postcss.config.js
├── public
├── README.md
├── search.json
├── src
│   └── app
│       ├── authors
│       │   └── [slug]
│       │       └── page.tsx
│       ├── BlogLayout.tsx
│       ├── cards.min.css
│       ├── Card.tsx
│       ├── error.tsx
│       ├── favicon.ico
│       ├── Footer.tsx
│       ├── ghost-client.ts
│       ├── globals.css
│       ├── Header.tsx
│       ├── layout.tsx
│       ├── not-found.tsx
│       ├── pages
│       │   └── [slug]
│       │       └── page.tsx
│       ├── page.tsx
│       ├── pagination
│       │   └── [item]
│       │       └── page.tsx
│       ├── Pagination.tsx
│       ├── read
│       │   └── [slug]
│       │       ├── Newsletter.tsx
│       │       └── page.tsx
│       ├── Search.tsx
│       ├── SocialIcons.tsx
│       └── tags
│           └── [slug]
│               └── page.tsx
├── tailwind.config.js
└── tsconfig.json

13 directories, 30 files

How to Configure Ghost CMS and Next.js

The next step is to set up data fetching for the Ghost Content API. This is why we installed the @tryghost/content-api package above.

Ghost CMS comes with two types of APIs: the first is the Content API, and the second is the Admin API. For the blog, we'll use the Content API.

Content API is a RESTful API that fetches the published content for the Ghost database. It is a read-only API. You can not call POST requests with it.

To configure it, we create a new file inside the src/app folder with ghost-client.ts. Inside the file, we have a new Ghost API instance.

// ghost-client.ts

import GhostContentAPI from "@tryghost/content-api";

// Create API instance with site credentials
const api = new GhostContentAPI({
  url: process.env.GHOST_URL as string,
  key: process.env.GHOST_KEY as string,
  version: "v5.0"
});

We need the blog URL, key, and version to config the Ghost content API in Next. You can find both the URLs and Key properties in the Ghost dashboard, as well as the version value which is your current version of Ghost CMS.

Go to the Ghost dashboard:

Get your KEY and URL

Go to dashboard > settings > integrations > Your-intergration-id and get your GHOST_URL and GHOST_KEY . Now you can copy both and paste them inside your .env.local file.

_Get your GHOST_KEY and GHOST_URL_

Understanding the Next.js 13 App Folder

There have been lots of changes in the Next.js pages folder and app folder with the release of Next.js 13. We'll discuss some important stuff now and more when we're building the app:

1. There is no _app , _document, getServerSideProps, getStaticProps, getStaticPaths , 404 and useRouter.
2. Now it combines the _app and _document files with the layout file.
3. useRouter is import from next/navigation.
4. The 404 file is replaced by the notFound() function.
5. The error.tsx file provides functionality like reacting to error boundaries.
6. Now the index.js file is replaced by page.js.
7. Passing dynamic route segments pages/blog/[slug].js is changed, and the Next app directory looks like this: app/blog/[slug]/page.js.

Examples

To understand the Next experimental app folder, let's look at a real example:

1. tag page => app/tag/[slug]/page.ts
2. category => app/tag/[slug]/page.ts

Now you can create five files inside every route. For example, if you create a tag or category route in your app folder, then you can create four files inside your app route folder.

• page.ts (required): it is your main file.
• layout.ts (optional): it helps design your layout
• loading.ts (optional): it creates a loading indicator with React suspense.
• error.ts (optional): it helps handle errors in your React app.
• components (optional): you can also create another component in your routes.

Let's understand how the new Next.js 13 app route works with a real-life example: your tag route folder looks like this.

app/tag/[slug]/page.ts
app/tag/[slug]/loading.ts
app/tag/[slug]/layout.ts
app/tag/[slug]/error.ts
app/tag/[slug]/my-card-component.ts

Demo Data for the Project

You don't have to worry about creating a demo or dummy blog post data. For your testing, You can download it from this GitHub repository.

How to Build the Blog

We'll go through and build each part of the blog in the following sections so you can follow along at home.

1. How to build the header
2. How to build the footer
3. How to build the layout
4. How to build the homepage
5. How to build the reading page
6. How to build the tag page
7. How to build the author page
8. How to build single pages
9. How to handle pagination
10. Next.js SEO
11. How to Enable Search
12. Error Handling
13. How to rebuild your static site with webhooks

How to Build the Header

The first and main part of the site is the header. First, we'll create a simple header for our demo blog. Our header will end up looking like this:

Design of the header

First is the logo, next comes the nav bar with various elements, and last is the icon section. All the data comes from the Ghost CMS API. You can change things inside Ghost CMS and it will reflect on the site.

Here's the code to build the header component:

// Header.tsx

import Link from "next/link";
import SocialIcons from "./SocialIcons";
import Image from "next/image";
import type { Settings } from "@tryghost/content-api";

function Header({ setting }: { setting: Settings }) {

  return (
    <header className="px-2 sm:px-4 py-2.5 dark:bg-gray-900 w-full">

      <div className="container flex flex-wrap items-center justify-between mx-auto">
        {/* Logo for blog */}
        <Link href="/" className="flex items-center">
          {setting.logo !== null ?
            <Image
              alt={setting.title} width={200} height={100} src={setting.logo} className="self-center text-xl font-semibold whitespace-nowrap dark:text-white" />
            : setting.title}
        </Link>
        <div className="flex md:order-2">

          <ul className="flex flex-wrap p-4 md:space-x-8 md:mt-0 md:text-sm md:font-medium">

            {
              /* Blog Navigation Edit in GHOST CMS  */
              setting.navigation !== undefined ? setting?.navigation.map(item => <li key={item.label} className="block py-2 pl-3 pr-4 text-gray-700 rounded hover:text-blue-700 dark:hover:text-blue-700 md:p-0 dark:text-white"
                aria-current="page">
                <Link href={item.url}>
                  {item.label}
                </Link>
              </li>) : " "

            }

          </ul>

        </div>
        <SocialIcons setting={setting} />
      </div>

    </header >
  )

}
export default Header

How to Build the Footer

The footer is also an important section of a blog site. It shows your important information and various helpful links.

Design of the footer

I designed a basic footer with copyrighted text and added social icons for the site. The social icons come from the Ghost CMS API.

// Footer.tsx

import { FaTwitter, FaFacebook } from "react-icons/fa";
import Link from "next/link";
import type { Settings } from "@tryghost/content-api";

function Footer({ setting }: { setting: Settings }) {

  return (

    <footer className="px-2 sm:px-4 py-2.5 dark:bg-gray-900 w-full">

      <div className="container flex flex-wrap items-center justify-between mx-auto">

        <Link href="https://github.com/frontendweb3" className="flex items-center">
          <span className="self-center text-gray-800 text-sm font-semibold whitespace-nowrap dark:text-white">2023 copyright frontend web</span>
        </Link>

        <div className="flex md:order-2">

          <ul className="flex p-4 flex-row md:space-x-8 md:mt-0 md:text-sm font-medium">

            {
              setting.twitter !== null ? <li>
                <Link target="_blank" href={`https://twitter.com/${setting.twitter}`} className="block py-2 pl-3 pr-4 text-gray-700 rounded hover:text-blue-700 dark:hover:text-blue-700 md:p-0 dark:text-white" aria-current="page">
                  <FaTwitter />
                </Link>
              </li> : " "

            }

            {
              setting.facebook !== null ? <li>
                <Link target="_blank" href={`https://www.facebook.com/${setting.facebook}`} className="block py-2 pl-3 pr-4 text-gray-700 rounded hover:text-blue-700 dark:hover:text-blue-700 md:p-0 dark:text-white ">
                  <FaFacebook />
                </Link>
              </li> : " "

            }

          </ul>
        </div>

      </div>
    </footer>

  )
}

export default Footer

How to Build the Layout

I designed a basic layout for the blog. For building layouts in Next.js, there's a special layout.tsx file.

Before we create the layout design, we need to define a getNavigation function to fetch navigation and basic website-related data from Ghost.

// ghost-client.ts


export async function getNavigation() {
  return await api.settings.browse()
}

The data look like this:

{
  title: 'Rajdeep Singh',
  description: 'Thoughts, stories and ideas.',
  logo: 'http://localhost:2368/content/images/2023/04/nextjsandghostlogo-2.png',
  icon: 'http://localhost:2368/content/images/size/w256h256/2023/04/nextjs-60pxx60px.png',
  accent_color: '#d27fa0',
  cover_image: 'https://static.ghost.org/v4.0.0/images/publication-cover.jpg',
  facebook: 'ghost',
  twitter: '@ghost',
  lang: 'en',
  locale: 'en',
  timezone: 'Etc/UTC',
  codeinjection_head: null,
  codeinjection_foot: null,
  navigation: Array(5) [
    { label: 'Home', url: '/' }, { label: 'JavaScript', url: '/tags/javascript/' }, { label: 'Nextjs', url: '/tags/nextjs/' },
    { label: 'Reactjs', url: '/tags/reactjs/' }, { label: 'Ghost CMS', url: '/tags/ghost-cms/' }
  ],
  secondary_navigation: Array(1) [ { label: 'Login', url: '#/portal/' } ],
  meta_title: 'My demo post',
  meta_description: 
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry\'s standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.',
  og_image: null,
  og_title: null,
  og_description: 
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry\'s standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.',
  twitter_image: null,
  twitter_title: null,
  twitter_description: 
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry\'s standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.',
  members_support_address: 'noreply',
  members_enabled: true,
  members_invite_only: false,
  paid_members_enabled: false,
  firstpromoter_account: null,
  portal_button_style: 'icon-and-text',
  portal_button_signup_text: 'Subscribe',
  portal_button_icon: null,
  portal_plans: Array(1) [ 'free' ],
  portal_name: true,
  portal_button: true,
  comments_enabled: 'all',
  url: 'http://localhost:2368/',
  version: '5.39'
}

The getNavigation function returns the settings data, and then we pass the data as props into the header and footer components.

Our Main layout.tsx file works server side. It helps fetch data on the server side with the React use hook.

// Layout.tsx


import "./globals.css";
import BlogLayout from './BlogLayout'
import { getNavigation, } from "./ghost-client"
import { use } from "react"
import type { Settings } from "@tryghost/content-api"

interface UpdateSettings extends Settings {
  accent_color?: string;
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {

  const settings: UpdateSettings = use(getNavigation())

  return (

    <html className='light' lang="en">

      <body
        style={{
          '--bg-color': settings?.accent_color ? settings.accent_color : "",
        }}
        className={` bg-[--bg-color] dark:bg-gray-900`}>

        <BlogLayout setting={settings}>

          {children}

        </BlogLayout>

      </body>

    </html>

  )
}

BlogLayout component

The BlogLayout component works on the client side. In the Next.js app folder, you can easily convert your server-side component to the client side with the following "use client" syntax.

The purpose of the BlogLayout component is to contain the ThemeProvider, header, and footer. ThemeProvider is a high-order component, and it provides additional functionality, like changing the theme from dark to light. We wrap the intra-site with ThemeProvider's higher component. In the old pages directory, we achieve similarly functionally with nextjs _app.ts custom app.

ThemeProvider component helps to change the theme from light to dark mode.

"use client"

// BlogLayout.tsx

import Footer from "./Footer";
import Header from "./Header";
import { ThemeProvider } from 'next-themes';
import type { Settings } from "@tryghost/content-api";
function Layout({ setting, children }: { setting: Settings, children: React.ReactNode }) {
  return <ThemeProvider attribute="class">
    <Header setting={setting} />
    {children}
    <Footer setting={setting} />
  </ThemeProvider>

}
export default Layout

How to Build the Homepage

Next.js has a special app/page.tsx file for designing and building the home page. Our blog website's home page looks like what you see below. We import the header, card, pagination, and footer on the home page. The header and footer are part of layout.tsx.

Home page

First, we fetch all posts data from Ghost CMS with the help of the getPosts function, which I defined in the ghost-client.ts file.

// ghost-client.ts

export async function getPosts() {
  return await api.posts
    .browse({
      include: ["tags", "authors"],
      limit: 10
    })
    .catch(err => {
      throw new Error(err)
    });
}

By default, the api.post.browse() returns only post data, but you can easily extend it. In every article or post data, we also include tags and authors with the help of include. Then we set the article limit to ten.

The data look like this:

 [
  {
    id: '6422a742136f5d40f37294f5',
    uuid: '8c2fcfda-a6e4-4383-893b-ba18511c0f67',
    title: 'Demo Posts with Nextjs and Ghost Editor',
    slug: 'demo-posts-with-nextjs-and-reactjs',
    html: `<p><strong>Lorem Ipsum</strong> is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text si
nce the 1500s when an unknown printer scrambled a galley of type and scrambled it to make a type specimen book. </p><p>It has survived five centuries and the leap i
nto electronic typesetting, remaining essentially unchanged. </p><p>It was popularised in the 1960s with Letraset sheets containing Lorem Ipsum passages and, more r
ecently, desktop publishing software like Aldus PageMaker, including versions of Lorem Ipsum.</p><figure class="kg-card kg-gallery-card kg-width-wide kg-card-hascap
tion"><div class="kg-gallery-container"><div class="kg-gallery-row"><div class="kg-gallery-image"><img src="http://localhost:2368/content/images/2023/03/Build-and-d
eploy.png" width="1500" height="400" loading="lazy" alt srcset="http://localhost:2368/content/images/size/w600/2023/03/Build-and-deploy.png 600w, http://localhost:2
368/content/images/size/w1000/2023/03/Build-and-deploy.png 1000w, http://localhost:2368/content/images/2023/03/Build-and-deploy.png 1500w" sizes="(min-width: 720px)
 720px"></div><div class="kg-gallery-image"><img src="http://localhost:2368/content/images/2023/03/Build-and-deploy-profile-1.png" width="1500" height="400" loading
="lazy" alt srcset="http://localhost:2368/content/images/size/w600/2023/03/Build-and-deploy-profile-1.png 600w, http://localhost:2368/content/images/size/w1000/2023
/03/Build-and-deploy-profile-1.png 1000w, http://localhost:2368/content/images/2023/03/Build-and-deploy-profile-1.png 1500w" sizes="(min-width: 720px) 720px"></div>
</div><div class="kg-gallery-row"><div class="kg-gallery-image"><img src="http://localhost:2368/content/images/2023/03/Build-and-deploy-profile--1--1.png" width="15
00" height="400" loading="lazy" alt srcset="http://localhost:2368/content/images/size/w600/2023/03/Build-and-deploy-profile--1--1.png 600w, http://localhost:2368/co
ntent/images/size/w1000/2023/03/Build-and-deploy-profile--1--1.png 1000w, http://localhost:2368/content/images/2023/03/Build-and-deploy-profile--1--1.png 1500w" siz
es="(min-width: 720px) 720px"></div><div class="kg-gallery-image"><img src="http://localhost:2368/content/images/2023/03/Build--Test-and-Deploy-profile-1.png" width
="1500" height="400" loading="lazy" alt srcset="http://localhost:2368/content/images/size/w600/2023/03/Build--Test-and-Deploy-profile-1.png 600w, http://localhost:2
368/content/images/size/w1000/2023/03/Build--Test-and-Deploy-profile-1.png 1000w, http://localhost:2368/content/images/2023/03/Build--Test-and-Deploy-profile-1.png 
1500w" sizes="(min-width: 720px) 720px"></div></div></div><figcaption>Build and deploy</figcaption></figure><h2 id="why-do-we-use-it">Why do we use it?</h2><p>It is
 a long-established fact that a reader will be distracted by the readable content of a page when looking at its layout. </p><p>The point of using Lorem Ipsum is tha
t it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English. </p><p>Many desktop 
publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for 'lorem ipsum' will uncover many web sites still in their 
infancy. </p><p>Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like).</p><hr><h2 id="where-can-i
-get-some">Where can I get some?</h2><p>There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by i
njected humour, or randomised words which don't look even slightly believable. </p><p>If you are going to use a passage of Lorem Ipsum, you need to be sure there is
n't anything embarrassing hidden in the middle of text. </p><p>All the Lorem Ipsum generators on the Internet tend to repeat predefined chunks as necessary, making 
this the first true generator on the Internet. </p><p>It uses a dictionary of over 200 Latin words, combined with a handful of model sentence structures, to generat
e Lorem Ipsum which looks reasonable. </p><p>The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc.</
p><div class="kg-card kg-callout-card kg-callout-card-red"><div class="kg-callout-emoji">💡</div><div class="kg-callout-text">My note is here&nbsp;</div></div><p></
p><div class="kg-card kg-header-card kg-width-full kg-size-small kg-style-dark" style data-kg-background-image><h2 class="kg-header-card-header" id="product">Produc
t</h2><h3 class="kg-header-card-subheader" id="my-blog-list">My blog list</h3></div><p></p><figure class="kg-card kg-embed-card kg-card-hascaption"><iframe width="2
00" height="113" src="https://www.youtube.com/embed/_q1K7cybyRk?feature=oembed" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gy
roscope; picture-in-picture; web-share" allowfullscreen title="Next.js 13.1 Explained!"></iframe><figcaption>youtube</figcaption></figure><hr><figure class="kg-card
 kg-embed-card"><blockquote class="twitter-tweet"><p lang="en" dir="ltr">In 2022, we enabled developers to create at the moment of inspiration, now with over 2 mill
ion deployments per week.<br><br>Here&#39;s what we shipped ↓ <a href="https://t.co/6k7Xmbpna3?ref=localhost">pic.twitter.com/6k7Xmbpna3</a></p>&mdash; Vercel (@ver
cel) <a href="https://twitter.com/vercel/status/1611094825587167254?ref_src=twsrc%5Etfw&ref=localhost">January 5, 2023</a></blockquote>\n` +
      '<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>\n' +
      '</figure><hr><figure class="kg-card kg-bookmark-card kg-card-hascaption"><a class="kg-bookmark-container" href="https://medium.com/frontendweb/what-is-progre
ssive-web-app-and-how-to-enable-it-in-nextjs-application-17f2e3240390?ref=localhost"><div class="kg-bookmark-content"><div class="kg-bookmark-title">What is Progres
sive Web App and How to enable it in nextjs Application?</div><div class="kg-bookmark-description">A detailed guide to Progressive Web Apps: How to use it with next
js and publish on Google play store, Microsoft store, Meta Quest, and…</div><div class="kg-bookmark-metadata"><img class="kg-bookmark-icon" src="https://cdn-static-
1.medium.com/_/fp/icons/Medium-Avatar-500x500.svg" alt><span class="kg-bookmark-author">FrontEnd web</span><span class="kg-bookmark-publisher">Rajdeep singh</span><
/div></div><div class="kg-bookmark-thumbnail"><img src="https://miro.medium.com/v2/resize:fit:1200/1*yAoHfq4Wm2Bp8DU1Dav29Q.png" alt></div></a><figcaption>Bookmark<
/figcaption></figure><div class="kg-card kg-header-card kg-width-full kg-size-small kg-style-dark" style data-kg-background-image><h2 class="kg-header-card-header" 
id="thank-you">Thank you</h2></div>',
    comment_id: '6422a742136f5d40f37294f5',
    feature_image: 'https://images.unsplash.com/photo-1543966888-7c1dc482a810?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=MnwxMTc3M3wwfDF8c2VhcmNofDE2fHxqYXZhc2Nya
XB0fGVufDB8fHx8MTY3OTk5MjY1NA&ixlib=rb-4.0.3&q=80&w=2000',
    featured: false,
    visibility: 'public',
    created_at: '2023-03-28T08:37:22.000+00:00',
    updated_at: '2023-03-28T08:51:38.000+00:00',
    published_at: '2023-03-28T08:50:44.000+00:00',
    custom_excerpt: 'It has survived five centuries and the leap into electronic typesetting, remaining essentially unchanged. ',
    codeinjection_head: null,
    codeinjection_foot: null,
    custom_template: null,
    canonical_url: null,
    tags: [ [Object] ],
    authors: [ [Object] ],
    primary_author: {
      id: '1',
      name: 'Rajdeep Singh',
      slug: 'rajdeep',
      profile_image: 'https://www.gravatar.com/avatar/dafca7497609ae294378279ad1d6136c?s=250&r=x&d=mp',
      cover_image: null,
      bio: 'Lorem Ipsum is simply dummy text of the printing and typesetting industry. ',
      website: 'https://officialrajdeepsingh.dev',
      location: 'India',
      facebook: 'officialrajdeepsingh',
      twitter: '@Official_R_deep',
      meta_title: null,
      meta_description: null,
      url: 'http://localhost:2368/author/rajdeep/'
    },
    primary_tag: {
      id: '6422aa9a136f5d40f3729552',
      name: 'demo',
      slug: 'demo',
      description: null,
      feature_image: null,
      visibility: 'public',
      og_image: null,
      og_title: null,
      og_description: null,
      twitter_image: null,
      twitter_title: null,
      twitter_description: null,
      meta_title: null,
      meta_description: null,
      codeinjection_head: null,
      codeinjection_foot: null,
      canonical_url: null,
      accent_color: null,
      url: 'http://localhost:2368/tag/demo/'
    },
    url: 'http://localhost:2368/demo-posts-with-nextjs-and-reactjs/',
    excerpt: 'It has survived five centuries and the leap into electronic typesetting, remaining essentially unchanged. ',
    reading_time: 3,
    access: true,
    comments: true,
    og_image: null,
    og_title: null,
    og_description: null,
    twitter_image: null,
    twitter_title: null,
    twitter_description: null,
    meta_title: null,
    meta_description: null,
    email_subject: null,
    frontmatter: null,
    feature_image_alt: 'Demo Posts with Nextjs and Ghost Editor',
    feature_image_caption: 'Photo by <a href="https://unsplash.com/@pinjasaur?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Paul Esch-Laurent</a> / 
<a href="https://unsplash.com/?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Unsplash</a>'
  },
meta:{
    pagination: { page: 1, limit: 10, pages: 2, total: 12, next: 2, prev: null }
  }
]

Now we call the getPosts function on the server side. It returns all the post data with the associated tags and authors. Now you can loop through the data with a map() function.

We pass the data into app/page.tsx to the card.tsx components. We pass the article data as props into the card component.

// src/app/page.tsx

import { getPosts } from "./ghost-client"
import Card from './Card'

export default async function Home() {

  const getPost = await getPosts()

  return (
    <>
      <main className="container my-12 mx-auto grid grid-cols-1 gap-2 md:gap-3 lg:gap-4 lg:grid-cols-3 md:grid-cols-2 xl:grid-cols-4 2xl:grid-cols-4">

        {
          getPost?.map(
            item => {
              return <Card key={item.uuid} item={item} />
            })
        }

      </main>

    </>
  )
}

Card component

I designed a basic card for the blog. The card component looks like this:

Card component

I rendered every item of data coming from the home page as props and showed it on the site with Card.tsx .

// Card.tsx

import Image from "next/image"
import Link from "next/link"
import type { PostOrPage } from "@tryghost/content-api";
import { format } from 'date-fns'

function Card({ item }: { item: PostOrPage }) {

  return (
    <div className="max-w-full bg-white dark:bg-gray-800" >

      {
        item.featured !== null && item.feature_image !== undefined ? <Link href={`/read/${item.slug}`}>
          <Image className="rounded-lg p-3" width={1000} height={324} src={item.feature_image} alt={item.feature_image_alt || item.title} />
        </Link> : " "
      }

      <div className="p-3">

        <div className="flex mb-3">
          {
            item.published_at !== null && item.published_at !== undefined ? <p className="text-sm text-gray-500 dark:text-gray-400">
              {format(new Date(item.published_at), 'dd MMMM, yyyy')}
            </p> : ""
          }
          <p className="text-sm text-gray-500 dark:text-gray-400 mx-1"> , </p>
          <p className="text-sm text-gray-500 dark:text-gray-400">
            {item.reading_time} min read
          </p>
        </div>

        <Link href={`/read/${item.slug}`}>
          <h5 className="mb-2 text-2xl font-bold tracking-tight text-gray-900 dark:text-white">
            {item.title}
          </h5>
        </Link>


      </div>

    </div>

  )

}



export default Card

How to Build the Reading Page

The reading page is the second most important page for the blog site. If people can't figure out how to read what the author writes, this is a big problem for front-end developers.

Reading page

First, we get a single article from the Ghost CMS API based on its slug. We pass it to the Card component with the Link component.

// ghost-client.ts

export async function getSinglePost(postSlug: string) {
  return await api.posts
    .read({
      slug: postSlug
    }, { include: ["tags", "authors"] })
    .catch(err => {
      console.error(err);
    });
}

The getSinglePost(<you-slug>) function returns data about a single article, and you can render that data on the page.

// src/app/read/[slug]/page.tsx

import Newsletter from "./Newsletter";
import Link from "next/link";
import { getSinglePost, getPosts } from "../../ghost-client"
import Image from "next/image";
// import icon
import { FaAngleLeft } from "react-icons/fa";

// types for typescript
import type { Metadata } from "next";
import type { PostOrPage } from "@tryghost/content-api";

// format the date
import { format } from 'date-fns'

// css for card
import "../../cards.min.css"


export async function generateStaticParams() {
  const posts = await getPosts()
  return posts.map((post) => ({
    slug: post.slug,
  }));
}


async function Read({ params }: { params: { slug: string }; }) {

  const getPost = await getSinglePost(params.slug)

  return (
    <>
      <main className="pt-8 pb-16 lg:pt-16 lg:pb-24 dark:bg-gray-900">

        <div className="flex justify-between px-4 mx-auto max-w-screen-xl ">

          <article className="mx-auto w-full max-w-3xl prose prose-xl prose-p:text-gray-800  dark:prose-p:text-gray-100 sm:prose-base prose-a:no-underline prose-blue dark:prose-invert">

            <div className="flex mb-4 w-full justify-between">

              <Link className="inline-flex items-center" href={`/`}>
                <FaAngleLeft /> Back
              </Link>

              {
                getPost.primary_tag ? <Link href={`/tags/${getPost?.primary_tag.slug}`}>
                  # {getPost?.primary_tag.name}
                </Link> : ""
              }

            </div>

            <h1 className="mb-4 text-3xl font-extrabold leading-tight text-gray-900 lg:mb-6 lg:text-4xl dark:text-white">
              {getPost.title}
            </h1>

            <p className="lead">
              {getPost.excerpt}
            </p>

            <header className="mb-4 lg:mb-6 not-format">

              <address className="flex items-center mb-6 not-italic">

                <div className="inline-flex items-center mr-3 text-sm text-gray-900 dark:text-white">

                  <Image width={32} height={32} className="mr-4 w-10 h-10 rounded-full" src={getPost?.primary_author.profile_image} alt={getPost?.primary_author.name} />
                  {
                    getPost.primary_author ? <Link href={`/authors/${getPost?.primary_author.slug}`} rel="author" className="text-xl font-bold text-gray-800 dark:text-white">{getPost?.primary_author.name}</Link> : " "
                  }

                  {
                    getPost.published_at ? <time className="text-base font-light text-gray-800 dark:text-white mx-1" dateTime={getPost?.published_at} title={format(new Date(getPost?.published_at), 'yyyy-MM-dd')}>
                      {format(new Date(getPost?.published_at), 'dd MMMM, yyyy')}
                    </time> : ""
                  }

                  <div className="text-base w-1 h-1 rounded-full bg-black dark:bg-white mx-1"></div>

                  <p className="text-base font-light text-gray-500 dark:text-gray-400"> {getPost.reading_time}  Min Read</p>

                </div>

              </address>

            </header>

            <figure>
              <Image className="mx-auto" width={1000} height={250} src={getPost.feature_image} alt={getPost.feature_image_alt} />
              <figcaption className="text-center"
                dangerouslySetInnerHTML={{
                  __html: getPost?.feature_image_caption
                }}></figcaption>
            </figure>

            <div dangerouslySetInnerHTML={{ __html: getPost?.html }}></div>

          </article>
        </div>
      </main>
      <Newsletter />
    </>
  )

}
export default Read

You render the post's HTML data with dangerouslySetInnerHTML . But you need to write lots of CSS to handle the dynamic content coming from the Ghost CMS API.

To solve that, I used the @tailwindcss/typography package. I also downloaded cards.min.css from Ghost. Now you don't need to write a single line of CSS in your Next app.

Generate the static site with the generateStaticParams function. Before, we used to getStaticProps function.

// ghost-client.ts


export async function generateStaticParams() {

  // fetch All posts

  const posts = await getPosts()

  // return the slug 

  return posts.map((post) => ({
    slug: post.slug,
  }));

}

How to Build the Tag Page

I designed a simple tag page for the blog. The tag page shows articles related to the tags that are used.

You can also create a category page. Tag pages and category pages use the same logic and functionalities.

Tag page

Similar to the reading page, we'll get articles based on tags from the Ghost CMS API.

// ghost-client.ts


// return all posts realted to tag slug
export async function getTagPosts(tagSlug: string) {

  return await api.posts.browse({ filter: `tag:${tagSlug}`, include: 'count.posts' })
    .catch(err => {
      throw new Error(err)
    });
  ;

}

// return all the slugs to build static with generateStaticParams
export async function getAllTags() {
  return await api.tags.browse({
    limit: "all"
  }).catch(err => {
    console.log(err)
  })
}

The getTagPosts(<tag-slug>) function returns all the available posts related to a specific tag.

After receiving all posts with getTagPosts(), we render all posts with the help of the map() method.

// src/app/tag/[slug]/page.tsx

import React from 'react'
import Card from "../../Card"

import { getTagPosts, getAllTags } from "../../ghost-client"

import { notFound } from 'next/navigation';

import type { PostsOrPages } from "@tryghost/content-api";


export async function generateStaticParams() {

  const allTags: Tags = await getAllTags()

  let allTagsItem: { slug: string }[] = []

// genrate the slug for static site

  allTags?.map(item => {
    allTagsItem.push({
      slug: item.slug,
    })
  })

  return allTagsItem

}


async function Tag({ params }: { params: { slug: string }; }) {

  let tagPosts: PostsOrPages = await getTagPosts(params.slug)

// Handling 404 error

  if (tagPosts.length === 0) {
    notFound()
  }

  return (
    <aside aria-label="Related articles" className="py-8 lg:py-24 dark:bg-gray-800">

      <div className="px-4 mx-auto max-w-screen-xl">

        <h2 className="mb-8 text-2xl font-bold text-gray-900 dark:text-white">
          More articles from {params.slug.split("-").join(" ")}
        </h2>

        <div className="container my-12 mx-auto grid grid-cols-1 gap-12 md:gap-12 lg:gap-12  lg:grid-cols-3  md:grid-cols-2 xl:grid-cols-4 2xl:grid-cols-4 ">

          {
            tagPosts.map(
              item => <Card key={item.uuid} item={item} />
            )
          }

        </div>

      </div>

    </aside>
  )

}

export default Tag

Generate the static site with the generateStaticParams function. It helps to generate slugs of the static build.

// ghost-client.ts

export async function getAllTags() {
  return await api.tags.browse({
    limit: "all"
  }).catch(err => {
    console.log(err)
  })
}

How to Build the Author Page

The last and one of the most important pages for the blog site is the author page. This is where readers can learn more about the author.

For the demo blog, I designed a basic page for the author.

Author page

We'll build this in a similar way as we built the tag page. First, we get the author's metadata and author posts from the Ghost CMS API.

// ghost-client.ts


// get author meta Data

export async function getSingleAuthor(authorSlug: string) {
  return await api.authors
    .read({
      slug: authorSlug
    }, { include: ["count.posts"] })
    .catch(err => {
      console.log(err)
    });

}

// get author related posts

export async function getSingleAuthorPosts(authorSlug: string) {
  return await api.posts.browse({ filter: `authors:${authorSlug}` })
    .catch(err => {
      console.log(err)
    })
};

// get All author from Ghost CMS for generateStaticParams

export async function getAllAuthors() {

  return await api.authors
    .browse({
      limit: "all"
    })
    .catch(err => {
      throw new Error(err)
    });

}

The getSingleAuthor(<author-slug>) returns data about a single author based on the author slug, and the getSingleAuthorPosts(<author-slug>) function returns all posts related to the author.

We render the posts data with the help of the map() method.

// src/app/author/[slug]/page.tsx

import React from 'react';
import Link from "next/link";
import { FaFacebook, FaTwitter, FaGlobe } from "react-icons/fa";
import Card from "../../Card"

import { getSingleAuthor, getSingleAuthorPost, getAllAuthors } from "../../ghost-client"

import Image from 'next/image';
import { notFound } from 'next/navigation';

import type { Author, PostsOrPages } from "@tryghost/content-api";



export async function generateStaticParams() {

  const allAuthor: Author[] = await getAllAuthors()


  let allAuthorItem: { slug: string }[] = []

  allAuthor.map(item => {
    allAuthorItem.push({
      slug: item.slug,
    })
  })
  return allAuthorItem

}


async function AuthorPage({ params }: { params: { slug: string }; }) {

  const getAuthor: Author = await getSingleAuthor(params.slug)

  const allAuthor: PostsOrPages = await getSingleAuthorPost(params.slug)

// Handling 404 errors
  if (allAuthor?.length === 0) {
    notFound()
  }

  return (
    <>
      <section className="dark:bg-gray-900">
        <div className="py-8 px-4 mx-auto max-w-screen-xl lg:py-16 lg:px-6">

          <div className=" p-10 text-gray-500 sm:text-lg dark:text-gray-400">

            {
              getAuthor?.profile_image !== undefined ? <Image height={30} width={30} className="w-36 h-36 p-2 rounded-full mx-auto ring-2 ring-gray-300 dark:ring-gray-500" src={getAuthor?.profile_image} alt={getAuthor?.name} /> : ""
            }

            {
              getAuthor?.name ? <h2 className="mb-4 mt-4 text-4xl tracking-tight font-bold text-center text-gray-900 dark:text-white">
                {getAuthor?.name.split(" ")[0]}
                <span className="font-extrabold">
                  {getAuthor?.name?.split(" ")[1]}
                </span>
              </h2> : ""
            }

            <p className="mb-4 font-light text-center">{getAuthor?.bio} </p>


            <ul className="flex flex-wrap p-4 justify-center md:space-x-8 md:mt-0 md:text-sm md:font-medium">

              {
                (getAuthor?.website !== null) ? (<li>
                  <Link href={getAuthor?.website} className="block py-2 pl-3 pr-4 text-gray-700 hover:text-blue-700 dark:hover:text-blue-700 rounded md:p-0 dark:text-white" aria-current="page">
                    <FaGlobe />
                  </Link> </li>) : " "


              }

              {
                (getAuthor?.twitter !== null) ? (<li>
                  <Link href={getAuthor?.twitter} className="block py-2 pl-3 pr-4 text-gray-700 rounded hover:text-blue-700 dark:hover:text-blue-700 md:p-0 dark:text-white" aria-current="page">
                    <FaTwitter />
                  </Link>
                </li>) : " "
              }

              {
                (getAuthor?.facebook !== null && getAuthor.facebook !== undefined) ? (<li>
                  <Link href={getAuthor?.facebook}
                    className="block py-2 pl-3 pr-4 text-gray-700 rounded  hover:text-blue-700 dark:hover:text-blue-700 md:p-0 dark:text-white"> <FaFacebook />
                  </Link>
                </li>) : " "

              }

            </ul>

          </div>
        </div>
      </section>

      <aside aria-label="Related articles" className="py-8 lg:py-24 dark:bg-gray-800">
        <div className="px-4 mx-auto max-w-screen-xl">

          <h2 className="mb-8 text-2xl font-bold text-gray-900 dark:text-white">
            More articles from {getAuthor?.name}
          </h2>

          <div className="container my-12 mx-auto grid grid-cols-1 gap-12 md:gap-12 lg:gap-12  lg:grid-cols-3  md:grid-cols-2 xl:grid-cols-4 2xl:grid-cols-4 ">

            {
              allAuthor?.map(item => <Card key={item?.uuid} item={item} />)
            }

          </div>
        </div>
      </aside>


    </>
  )

}
export default AuthorPage

To generate the author slug for the static site, we need to use the generateStaticParams function. We do not need anything else to build the static site.

// ghost-client.ts


// Build Static Site 

export async function generateStaticParams() {

  const allAuthor: Author[] = await getAllAuthors()


  let allAuthorItem: { slug: string }[] = []

  allAuthor.map(item => {
    allAuthorItem.push({
      slug: item.slug,
    })
  })
  return allAuthorItem

}

How to Build Single Pages

For single pages like About, Contact, Privacy Policy, and so on, you can also create them with the Ghost Content API.

Our single-page design looks like this:

single blog page

Firstly, you need to fetch all pages and the single pages data from the Ghost Content API.

// ghost-client.tsx

// fetch all pages

export async function getSinglePage(pageSlug: string) {
  return await api.pages
    .read({
      slug: pageSlug
    })
    .catch(err => {
      console.error(err);
    });
}

// single page data 

export async function getSinglePage(pageSlug: string) {
  return await api.pages
    .read({
      slug: pageSlug
    }, { include: ["tags"] })
    .catch(err => {
      console.error(err);
    });
}

The getSinglePage(page-slug) function returns the single page data based on the page slug, and the getAllPages() function returns all the available published page data to generate the dynamic params with the generateStaticParams() function.

// src/app/pages/[slug]/page.tsx

import { getSinglePage, getAllPages } from "../../ghost-client"
import { notFound } from 'next/navigation';
import type { PostOrPage } from "@tryghost/content-api";
import "../../cards.min.css"

// genrate Static slug or params for blog

export async function generateStaticParams() {
  const pages = await getAllPages()

  return pages.map((post) => ({
    slug: post.slug,
  }));
}

async function Pages({ params }: { params: { slug: string }; }) {

// fetch single page
  const getPage = await getSinglePage(params.slug)

  // handle 404 error
  if (!getPage) {
    notFound()
  }

  return (
    <>
      <main className="pt-8 pb-16 lg:pt-16 lg:pb-24 dark:bg-gray-900">
        <div className="flex justify-between px-4 mx-auto max-w-screen-xl ">

          <article className="mx-auto w-full max-w-3xl prose prose-xl prose-p:text-gray-800  dark:prose-p:text-gray-100 sm:prose-base prose-a:no-underline prose-blue dark:prose-invert">


            <h1 className="mb-14 text-3xl font-extrabold leading-tight text-gray-900 lg:mb-6 lg:text-4xl dark:text-white">
              {getPage.title}
            </h1>

            <div dangerouslySetInnerHTML={{ __html: getPage?.html }}></div>

          </article>
        </div>
      </main>
    </>
  )

}
export default Pages

How to Handle Pagination

Pagination helps speed up your site as well as divide your site into smaller parts, more digestible pages. You can link your posts with each other with prev and next.

meta:{
    pagination: { page: 1, limit: 10, pages: 2, total: 12, next: 2, prev: null }
 }

Firstly, we'll create a Pagination.tsx file as a React component.

// Pagination.tsx

import Link from "next/link"
import { Pagination } from "@tryghost/content-api"

function PaginationItem({ item }: { item: Pagination }) {

  let paginationItems = []

  for (let index = 1; index <= item?.pages; index++) {
    paginationItems.push(<li key={index * 2} ><Link href={index === 1 ? "/" : `/pagination/${index}`} className="px-3 py-2 leading-tight bg-blue-100 hover:bg-blue-200 border-transparent border rounded-lg text-black dark:bg-gray-800 dark:text-gray-400 mx-2 dark:hover:bg-gray-700 dark:hover:text-white">
      {index}
    </Link></li>)
  }

  return (

    <nav aria-label="pagination" className="mx-auto my-20 container">

      <ul className="mx-auto flex justify-center -space-x-px">

        <li>
          {
            item.prev ? <Link href={item.prev === 1 ? "/" : `/pagination/${item.prev}`} className="px-3 py-2 mr-2 border border-transparent rounded-md  leading-tight bg-white hover:text-blue-700 dark:bg-gray-800 dark:text-gray-400
              dark:hover:bg-gray-700 dark:hover:text-white">
              Prev
            </Link> : " "
          }
        </li>

        {paginationItems}

        <li>
          {
            item.next ? <Link href={`/pagination/${item.next}`} className="px-3 py-2 ml-2 border border-transparent rounded-md leading-tight bg-white hover:text-blue-700 dark:bg-gray-800 dark:text-gray-400
            dark:hover:bg-gray-700 dark:hover:text-white">
              Next
            </Link> : " "
          }
        </li>


      </ul>

    </nav>

  )

}


export default PaginationItem

When you call the api.posts.browse({ limit: 10 }) request, the API endpoint returns ten posts and a meta object with pagination.

The returned api.posts.browse({ limit: 10 }) data look like this:

 [
  {title: 'Demo Posts with Nextjs and Ghost Editor',... },
  {title: Trigger the hook and rebuild the nextjs site',... }

meta:{
    pagination: { page: 1, limit: 10, pages: 2, total: 12, next: 2, prev: null }
  }
]

Now based on meta, we can create pagination and pass meta.pagination as props to the Pagination component.

// src/app/page.tsx

import { getPosts } from "./ghost-client"
import Pagination from "./Pagination"

export default async function Home() {

  const getPost = await getPosts()

  const AllPostForSerach = await getSearchPosts()

  return (
    <>
     {/* rest of code  */}
      <Pagination item={getPost.meta.pagination} />
    </>
  )
}

To enable dynamic pagination, we'll create a src/app/pagination/[item]/page.tsx route in the blog. You can use whatever name you want for the pagination route.

// ghost-client.tsx

// return all posts for generateStaticParams

export async function getPosts() {
  return await api.posts
    .browse({
      include: ["tags", "authors"],
      limit: 10
    })
    .catch(err => {
      throw new Error(err)
    });
}

// 
export async function getPaginationPosts(page: number) {
  return await api.posts
    .browse({
      include: ["tags", "authors"],
      limit: 10,
      page: page
    })
    .catch(err => {
      throw new Error(err)
    });
}

The getPosts is used to render the Pagination component on the pagination page. The important part is the getPaginationPosts(<pagination-page-number>) function, which returns posts based on the pagination page number.

// src/app/pagination/[item]/page.tsx

import { getPaginationPosts, getPosts } from "../../ghost-client"
import Card from '../../Card'
import PaginationItem from "../../Pagination"
import type { Metadata } from "next";
import type { PostsOrPages } from "@tryghost/content-api";




export async function generateStaticParams() {

  const posts:PostsOrPages = await getPosts()

  let paginationItem: { item: number }[] = []

  for (let index = 1; index <= posts?.meta.pagination.pages; index++) {
    paginationItem.push({
      item: index,
    })

  }

  return paginationItem

}



export default async function Pagination({ params }: { params: { item: string }; }) {

  let getParams: number = Number.parseInt(params.item)

  const getPost: PostsOrPages = await getPaginationPosts(getParams)

  return (
    <>

      <main className="container my-12 mx-auto grid grid-cols-1 gap-2 md:gap-3 lg:gap-4 lg:grid-cols-3 md:grid-cols-2 xl:grid-cols-4 2xl:grid-cols-4">

        {
          getPost?.map(
            item => {
              return <Card key={item.uuid} item={item} />
            })
        }
      </main>

      <PaginationItem item={getPost.meta.pagination} />

    </>
  )
}

Next.js SEO

If you are a blogger, you know how important SEO is in helping people find your blog and your articles. For SEO, Next.js provides a generateMetadata function to generate dynamic SEO metadata for your site. This means that you don't need any additional packages for SEO.

For the purpose of this example, I'll explain how to enable SEO for the blog only on the Homepage and the Reading page. You can use the same logic to enable it on any of your other pages.

First, let's see how to enable SEO on the Homepage:

// ghost-client.ts


// Get you settings meta data from Ghost CMS
export async function getNavigation() {
  return await api.settings.browse()
}

// src/app/page.tsx

import { getNavigation } from "./ghost-client"

export async function generateMetadata(): Promise<Metadata> {
  const Metadata = await getNavigation()
  return {
    title: Metadata.title,
    description: Metadata.description,
    keywords: ['Next.js', 'React', 'JavaScript'],
  }
}

Now we'll see how to enable SEO on the Reading page:

// ghost-client.ts


export async function getSinglePost(postSlug: string) {
  return await api.posts
    .read({
      slug: postSlug
    }, { include: ["tags", "authors"] })
    .catch(err => {
      console.error(err);
    });
}

The generateMetadata have params props, which help access the slug. Then, based on the slug, we get the data and return it.

export async function generateMetadata({ params }: { params: { slug: string }; }): Promise<Metadata> {

  const metaData: PostOrPage = await getSinglePost(params.slug)

  let tags = metaData?.tags.map(item => item.name)

  return {
    title: metaData.title,
    description: metaData.description,
    keywords: tags,
    openGraph: {
      title: metaData.title,
      description: metaData.excpet,
      url: metaData.url,
      keywords: tags,
      images: [
        {
          url: metaData.feature_image,
        },
      ],
      locale: metaData.locale,
      type: 'website',
    },
  }
}

How to Enable Search

Enabling search on a static blog is hard to do from scratch. Instead, you can use a third-party Node page like Orama or Flex search.

For our demo, we created a very simple search bar functionality without installing any additional packages.

Firstly, we get all posts from the Ghost CMS API.

// ghost-client.ts

export async function getSearchPosts() {
  return await api.posts.browse({ limit: "all"}).catch(err => {
    console.log(err)
  });

After we convert it into a string with the help of JSON.stringify(), we then create a new search.json file. On every request, it updates or rewrites our search.json file.

// src/app/page.tsx

import {  getSearchPosts } from "./ghost-client"
import * as fs from 'node:fs';



export default async function Home() {


// get All posts for search 
  const AllPostForSerach = await getSearchPosts()

  // Enable getSearch  

  try {

    const jsonString = JSON.stringify(AllPostForSerach)

    fs.writeFile('search.json', jsonString, 'utf8', err => {
      if (err) {
        console.log('Error writing file', err)
      } else {
        console.log('Successfully wrote file')
      }
    })

  } catch (error) {
    console.log('error : ', error)
  }


  return (
    <>
      <main className="container my-12 mx-auto grid grid-cols-1 gap-2 md:gap-3 lg:gap-4 lg:grid-cols-3 md:grid-cols-2 xl:grid-cols-4 2xl:grid-cols-4">
      {/* rest code... */}
      </main>
    </>
  )
}

When you enter the text in the search input, based on the text query, we compare the query or text in the serach.json file data. If it matches the article title with the query, then we store the searchPost variable, and finally we render the stored data in the searchPost variable page.

"use client"

import React, { useEffect, useState } from 'react';
import * as Popover from '@radix-ui/react-popover';
import { FaSearch } from "react-icons/fa";
import Link from 'next/link';
import searchData from '../../search.json'
import type { PostOrPage } from "@tryghost/content-api"


let searchPost: PostOrPage[] = []


function Search() {

  const [query, setQuery] = useState(null)

  useEffect(() => {

    searchPost.length = 0;

    searchData.map((item: PostOrPage) => {

      if (item?.title.trim().toLowerCase().includes(query?.trim().toLowerCase())) {
        searchPost.push(item)
      }

    })

  }, [query])


  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <button
          className="cursor-pointer outline-none"
          aria-label="Search"
        >
          <FaSearch />
        </button>
      </Popover.Trigger>

      <Popover.Portal>

        <Popover.Content
          className="rounded p-2 bg-white dark:bg-gray-800 w-[480px] will-change-[transform,opacity] data-[state=open]:data-[side=top]:animate-slideDownAndFade data-[state=open]:data-[side=right]:animate-slideLeftAndFade data-[state=open]:data-[side=bottom]:animate-slideUpAndFade data-[state=open]:data-[side=left]:animate-slideRightAndFade"
          sideOffset={5}
        >

          <div className='my-2'>
            <label htmlFor="default-search" className="mb-2 mt-5 text-sm font-medium text-gray-900 sr-only dark:text-white">Search bar </label>
            <div className="relative">
              <div className="absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none">
                <svg className="w-5 h-5 text-gray-500 dark:text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path></svg>
              </div>
              <input type="search" id="default-search" onChange={(event) => setQuery(event?.target.value)} className="block w-full p-4 pl-10 text-sm text-gray-900 border border-gray-300 rounded-lg bg-gray-50 focus:ring-blue-500 focus:border-blue-500 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500" placeholder="Start searching here ..." required />

            </div>
          </div>


          {

            serachPost.length > 0 ? serachPost.map(item => {

              return (
                <div key={item.uuid} className='my-3'>
                  <div className="text-white my-2 py-2 bg-blue-400 dark:bg-gray-900 dark:hover:bg-blue-400 border-none rounded-md dark:text-white">
                    <Link href={`read/${item.slug}`} className="relative inline-flex items-center rounded-lg w-full px-4 py-2 text-sm font-medium">
                      {item.title}
                    </Link>
                  </div>
                </div>
              )
            }) : " "

          }

        </Popover.Content>

      </Popover.Portal>

    </Popover.Root >
  )
}

export default Search;

Error Handling

Next.js has two types of error handling. the first is layout-based, and the second is global error handling. For the demo here, we'll use layout-based error handling.

Next provides a special type of error.tsx file to handle errors on your site. It does not handle 404, 500, and so on – it handles only runtime errors.

'use client'; // Error components must be Client components
import React from 'react';
import { useEffect } from 'react';
import Link from 'next/link';
export default function Error({ error, reset }: { error: Error; reset: () => void; }) {

  useEffect(() => {
    console.error(error);
  }, [error]);

  return (
    <section className="dark:bg-gray-900 my-16">

      <div className="py-8 px-4 mx-auto max-w-screen-xl lg:py-16 lg:px-6">

        <div className="mx-auto max-w-screen-sm text-center">

          <h1 className="mb-4 text-7xl tracking-tight font-extrabold lg:text-9xl text-primary-600 dark:text-primary-500">Something wrong</h1>
          <p className="mb-4 text-lg p-2 font-light bg-red-500 text-white dark:bg-red-400 dark:text-white">{error.message}</p>

          <div className='flex justify-around mt-2'>

            <Link href="#" className="inline-flex bg-gray-600 text-white hover:bg-gray-700 focus:ring-4 font-medium rounded-lg text-sm p-2
                text-center">Back to Homepage</Link>

            <button className='bg-gray-600 text-white rounded-lg p-2' onClick={() => reset()}>
              Try again
            </button>


          </div>

        </div>

      </div>

    </section>
  );
}

How to handle 404 errors

To handle 404 errors in the Next.js app folder, you need to create a not-found.tsx file in your root level.

Our 404 file looks like this:

404 error

Here's the code for that:

import Link from "next/link"

function NotFound() {

  return (
    <section className="bg-white dark:bg-gray-900 my-16">
      <div className="py-8 px-4 mx-auto max-w-screen-xl lg:py-16 lg:px-6">
        <div className="mx-auto max-w-screen-sm text-center">
          <h1 className="mb-4 text-7xl tracking-tight lg:text-9xl text-primary-600 dark:text-primary-500">404</h1>
          <p className="mb-4 text-3xl tracking-tight font-bold text-gray-900 md:text-4xl dark:text-white"> Something wrong</p>
          <p className="mb-4 text-lg font-light text-gray-500 dark:text-gray-400">
            Sorry, we cant find that article. You will find lots to explore on the home page.
          </p>
          <Link href="/" className="inline-flex text-white bg-black dark:bg-white dark:text-black p-3 hover:bg-gray-800 my-4">Back to Homepage</Link>
        </div>
      </div>
    </section >
  )

}

export default NotFound

The big issue with the not-found.tsx error file is that it doesn't show automatically in Next (v13.3.0). To show a 404 error, you need to show the error manually. Here's how you do that:

import { notFound } from 'next/navigation';

async function Read({ params }: { params: { slug: string }; }) {

  const getPost = await getSinglePost(params.slug)

  // if not found getPost, then show 404 error

  if (!getPost) {
    notFound()
  }

  return (
      <main className="pt-8 pb-16 lg:pt-16 lg:pb-24 dark:bg-gray-900">

          rest of code ....

      </main>
      )
}

How to Rebuild Your Static Site with Webhooks

The biggest problem when you create a static site happens if somebody writes a new post or changes an existing post in Ghost. For a personal project, you can manually redeploy your site. But for a larger site, you won't be able to do that every time this happens.

The best solution is to use webhooks. Ghost provides webhook support. If you update an existing post or write a new one, it'll update in Ghost.

In the demo project, we're using Vercel webhooks to deploy our blog. When we create a new blog or update something on the site, Ghost triggers the Vercel webhook. Then Vercel rebuilds the site as needed.

You do not need to write the code for this – just follow along and copy-paste as you go.

How to get the webhook from Vercel

Firstly, go to the Vercel dashboard.

Vercel dashboard

Select your project, where you'll deploy your Ghost frontend.

Select the project in your Vercel dashboard

Click on the settings tab in your Vercel project.

Click the Git tab

Then click on the Git tab. After scrolling down, you can see the deploy hook selection.

Go to Deploy hooks sections

Enter your webhook name and branch name and click on the "create hook" button.

Copy your webhook url

Click on the copy button to copy your vercel webhook.

How to integrate Vercel webhooks in the Ghost dashboard

When something changes in Ghost, it triggers the Vercel webhook URL. Then Vercel redeploys the blog site.

To integrate the Vercel webhook with Ghost, just follow these steps:

Open the Ghost CMS dashboard.

Ghost dashboard

Click on the setting icon.

Ghost settings

Click on the New custom integration button.

Add a new custom integration

Enter the integration name.

Add integration name

Click to add the webhook button.

How to add the webhook

First, enter the name, then select Event and paste the URL which you copied from the Vercel dashboard.

Based on the event, Ghost will call the webhook, and your website will rebuild. Redeploys take time based on how big your site is, and so on.

Conclusion

Everything should work well using Next.js and the Ghost CMS as we've worked through in this tutorial.

But some of the Ghost editor components, like toggles, where you need JavaScript interaction, don't work. You can solve this by writing your own JavaScript or getting a JavaScript file for Ghost and adding it to the read/[slug]/page.tsx file.

You can save a lot of money on hosting by combining Next.js and the Ghost CMS API, but you lose some features like inbuilt signup, login, accounts, subscriptions, search bar, and member access levels.

You can share and follow me on Twitter and Linkedin. If you like my work, you can read more content on my blog, the officialrajdeepsingh.dev, frontend web, and Sign up for my free newsletter.

You can also check out awesome-next, a curated list of awesome Nextjs-based libraries that help build small and large-scale applications with Next.js.

Here are some additional resources you can use if you need more help or information while going through this tutorial:

I write tons of articles on Next. If you are interested in Next and related stuff, you can follow me on Medium and join the frontend web publication.

Ghost targets primarily writers and all the features are specifically built for writing.

Ghost's new dashboard gives you a user-friendly interface, and beginners can easily understand the functionality. In addition, Ghost's free tutorials will help you if you have any problems.

Some cool Ghost features:

1. Open-source
2. Membership support
3. Rich text editor (Koenig editor)
4. Newsletters
5. Email subscriber support
6. Login functionality support
7. Integration plugin
8. Analytics dashboard
9. Inbuilt comment support
10. Inbuilt search support
11. Inbuilt search functionality
12. SEO and different types of metadata support social media
13. Custom theme design

You can check out all the code available for this project on GitHub here.

Here's what we'll cover:

1. Self-Hosting vs Hosting with Ghost
2. What Are the Drawbacks of Ghost?
3. How to Install the Ghost CMS
4. Understanding the Ghost Folder Structure
5. Understanding the Ghost Theme Folder Structure
6. How to Create a New Theme with the npm CLI Tool
7. How to Create a New Ghost Theme from Scratch
8. How to Install ghost-cli Globally
9. How to install Ghost locally
10. How to Configure Tailwind CSS
11. Other Important Commands in the Ghost CLI
12. How to Write the Code for Our Custom Ghost Theme
13. How to add theme configuration in package.json
14. How to Use Theme Helpers
15. What is the Partials Folder?
16. How to Create a Default Page
17. How to Create an Index Page
18. How to Create a Posts Page
19. How to Create Information Pages
20. How to Create an Author Page
21. How to Create a Tags Page
22. How to Create an Error Page
23. How to Enable Comments
24. How to Set Up Search
25. Conclusion

Self-hosting vs Hosting with Ghost

Ghost provides two ways to create/host your website:

1. Self-hosting
2. With the Ghost cloud platform

Self-hosting

If you choose to self-host, you'll host your website on any cloud platform like Google cloud, AWS cloud, Azure cloud, Digital Ocean, and so on. These are some of the most used cloud platforms in the market.

Most cloud platforms come with one click to deploy solutions. This means you can deploy your Ghost blog with a single click.

Before deploying your Ghost blog, you should compare all cloud platforms based on pricing before choosing one.

Self-hosting your Ghost blog is free, and you do not need to pay anything to the Ghost platform. You'll just pay your cloud provider.

Hosting with the Ghost Cloud Platform

If you choose to host with Ghost, they'll help create the blog and host it on the Ghost platform itself. The Ghost team handles all the maintenance and security. You won't have to worry about updating Ghost and any themes you're using – the Ghost staff will handle that for you.

Self-hosting focuses more on developers, while hosting with the Ghost platform targets anyone who doesn't know about computers and programming.

Ghost hosting comes with a paid plan – it's not free. But they give you 14 day free trial period, after which you shift automatically into a paid plan.

What should you choose, paid or self-hosting?

In my experience, hosting with the Ghost platform is the best solution for beginner developers, non-developers, and writers. The Ghost team handles everything for you. You do not worry about traffic, security, or maintenance and do not need to update the Ghost CMS. This lets you focus on writing.

As a developer, I always recommended that you self-host Ghost. I have run my self-hosted Ghost blog with Google Cloud for two years with a Bitnami one-click deployment.

After six months, I'd used up my $200 free credit, and then I started to pay monthly to Google Cloud hosting.

For a non-technical person, I highly recommended using the Ghost (pro) cloud platform and as well any other platform that provides Ghost-based cloud and shares hosting.

I found a list of Ghost-hosting platforms on the internet. Perhaps one of these will solve your hosting issues or questions. If you plan to deploy Ghost with the Google Cloud platform, I have an article on that.

What are the Drawbacks of Ghost CMS?

The biggest drawback of Ghost is that web performance can feel slow. If you want good web performance, you'll likely need to use a CDN for media (images, videos, and PDFs) and also for CSS and JavaScript.

The second biggest drawback is cost. I've been running my blog with Ghost for two years, and I pay 10 to 20 times extra to Google Cloud for hosting as a self-deploy.

My website has 4000 to 5000 active monthly users, and I pay 20 times extra. Because of this, I shifted my website to Hugo.

Now I still have 4000 to 5000 active users on the website, and I pay zero money to Netlify.

The Solution for Developers

The best solution for developers is to use Ghost as a backend and, with the REST API, choose any JavaScript framework like Next.js, Fresh, Astro, and so on.

There are a lot of frameworks that can help you build a static website. In addition, static websites are fast and deploy with zero JavaScript.

In this method, you may not use all Ghost's features, but you can save a lot of money. Still, building the website with a JavaScript framework takes a lot of time just to run the essential version of the website.

My solution only works well for a small team. So if your team has a lot of writers and submits many articles in a single day, I'd recommend sticking with Ghost CMS as a frontend and backend.

Ghost version 5.0 is 20% faster than the old version. Suppose you use Ghost and want to design your own custom theme – then this article is for you. Let's get started.

How to Install the Ghost CMS

How you install Ghost CMS changes according to your operating system. We'll discuss installation for all operating systems in this guide. You can install Ghost with npm, yarn, and Docker.

Now let's look at how to install Ghost for:

1. Windows, Linux, and macOS
2. Docker image

How to Install Ghost on Windows, Linux, and macOS

Setting up the Ghost theme development environment in Windows and macOS is a straightforward process. But it's best if you've installed the npm or yarn package manager. If you don't have Node.js, npm, and yarn, yolu'll need to install them – Node.js comes with preinstalled npm and yarn.

To install Ghost CMS globally and locally, follow these basic steps:

How to install ghost-CLI globally

First, you can install ghost-cli globally on your machine using npm or yarn. Here are the commands:

npm install ghost-cli@latest -g
    OR
yarn global add ghost-cli@latest

How to install Ghost locally

Next, when your ghost-CLI installation is complete, then run the ghost local command in your terminal. It looks like this:

ghost install local

The command output looks like this:

Ghost cms folder structure

Note: you'll need to run the ghost install local command in an empty folder. Otherwise, you'll face an error:

Not empty directory error with ghost-cli

To start the local development server, run the ghost start command in your terminal.

Ghost start command

If you get an error when running ghost start in Ubuntu, run the following command: ghost start --no-setup-linux-user.

The directory is not readable by other users' error in Ghost CMS.

How to Set Up Your Environment Using a Docker Image

Docker is also a great way to set up a theme development or production environment for Ghost. The Ghost team provides an official Ghost Docker image on Docker Hub.

To start the setup, you'll need the docker-compose.yml file in your root project folder. Then run the docker-compose up command in your terminal.

version: '3.8'
services:
  blog:
    image: ghost
    restart: always
    ports:
      - 8080:2368
    volumes:
      - ./custom-ghost-theme:/var/lib/ghost/content/themes/custom-ghost-theme/
    environment:
      url: http://localhost:808
      NODE_ENV: development

In the volume section, you pass your file. In my case, I added a specific file in my Ghost theme folder.

version: '3.8'
services:
  blog:
    image: ghost
    restart: always
    ports:
      - 8080:2368
    volumes:
      - ./assets:/var/lib/ghost/content/themes/fastest/assets
      - ./partials:/var/lib/ghost/content/themes/fastest/partials
      - ./author.hbs:/var/lib/ghost/content/themes/fastest/author.hbs
      - ./default.hbs:/var/lib/ghost/content/themes/fastest/default.hbs
      - ./error-404.hbs:/var/lib/ghost/content/themes/fastest/error-404.hbs
      - ./error.hbs:/var/lib/ghost/content/themes/fastest/error.hbs
      - ./gulpfile.js:/var/lib/ghost/content/themes/fastest/gulpfile.js
      - ./index.hbs:/var/lib/ghost/content/themes/fastest/index.hbs
      - ./package-lock.json:/var/lib/ghost/content/themes/fastest/package-lock.json
      - ./package.json:/var/lib/ghost/content/themes/fastest/package.json
      - ./page.hbs:/var/lib/ghost/content/themes/fastest/page.hbs
      - ./post.hbs:/var/lib/ghost/content/themes/fastest/post.hbs
      - ./query.hbs:/var/lib/ghost/content/themes/fastest/query.hbs
      - ./tag.hbs:/var/lib/ghost/content/themes/fastest/tag.hbs
      - ./readme.md:/var/lib/ghost/content/themes/fastest/readme.md
    environment:
      url: http://localhost:8080
      NODE_ENV: development

In your custom-ghost-theme folder, you need the index.hbs, post.hbs, and package.json files to start theme development. But, you'll get an error when you activate your theme in the Ghost dashboard without requiring a file.

Here's the GitHub repo if you want to follow along:

Errors

In Ubuntu (22.04) or any other Linux distros, you'll get the Message: The directory /home/rajdeepsingh/ is not readable by other users on the system error. This means yours is old. So update your ghost-cli then run the ghost start command in your folder.

Understanding the Ghost Folder Structure

The Ghost folder structure has three main folders and one file. They are:

1. The config.development.json file contains the configuration for Ghost development.
2. The current folder is a link (symbolic link) that targets the install version.
3. The version folder contains all versions of Ghost cms.
4. The content folder is the main folder containing our database file, settings, theme, images, media, and so on.

Ghost CMS folder Structure

The folder structure might change according to the operating system but the content folder is the same in every operating system.

The content folder contains all the important files for Ghost. They are:

1. The data folder contains an SQLite3 database file. Ghost, by default, uses the SQLite3 database.
2. Files, images, and media folders contain all files which writers upload.
3. The public folder contains all public CSS and JavaScript files – for example, card and member JavaScript and CSS files.
4. Finally, the settings folder contains all the settings, for example, the router.xml file.
5. The theme folder contains all files and folders used to develop the theme.

Understanding the Ghost Theme Folder Structure

You can build a new custom theme store in the content/theme folder. To develop a new theme, you'll always need to create a new folder with the theme name and store all files in the theme name folder.

// theme structure

content 
content/theme
content/theme/my-theme-name
content/theme/my-theme-name/index.hbs
content/theme/my-theme-name/post.hbs
content/theme/my-theme-name/package.json

// rest of file created in my-theme-name folder

Ghost CMS uses handlebars to build a Ghost theme. There are a number of files but only three files are required:

1. index.hbs in the main file (required) to design the home page of the website.
2. post.hbs the file (required) is used to read and design the full article.
3. package.json file (required) is used for Node.js config, and it also uses the theme name, description, version, custom config, and so on.
4. The default.hbs file is used to build the layout of the theme.
5. The assets folder contains all the JavaScript, CSS, fonts, and image files.
6. The partials folder helps divide files into small partials (parts) for better code readability.

Ghost theme folder structure

How to Create a New Theme with the npm CLI Tool

The easiest way to start a new Ghost theme is with the create-ghost-theme CLI. I built it, and I maintain it. The create-ghost-theme CLI helps you create the following folder structure that we'll discuss next. But currently, it only supports Tailwind CSS.

First, we'll create a new theme with the create-ghost-theme CLI and restart the Ghost CMS local server again.

Folder structure

After creating a new theme with create-ghost-theme CLI, your folder structure looks like this:

create-ghost-theme cli folder structure

Understanding the New Website Layout

After creating the theme with create-ghost-theme CLI, your theme looks like this.

index.hbs

Your website reading page will look like this:

Your new tag page looks like this:

How to Create a New Ghost Theme from Scratch

When you're learning about Ghost theme development, my recommendation is to start creating a new theme from scratch. Then you can use the CLI tool I just showed you. This will be a lot easier for you.

So now, that's what we're going to cover in-depth: how to create a new Ghost CMS theme from scratch.

Requirements:

To create a new theme, you'll need two libraries: the first is ghost-cli and the second is Tailwind CSS.

Here's what we'll go over in the coming sections:

1. How to install Ghost-cli globally
2. How to configure Tailwind CSS
3. How to understand more commands in the Ghost CLI
4. Finally, we'll write the code

How to Install ghost-cli Globally

We went over how to do this above, but in case you need a reminder here it is:

First, you can install ghost-cli globally on your machine using npm or yarn. Here are the commands:

npm install ghost-cli@latest -g
    OR
yarn global add ghost-cli@latest

How to Configure Tailwind CSS

Tailwind CSS is a powerful CSS library for designing the front end of a website. And you can easily use it with Ghost.

Install Tailwind CSS in your theme folder like this:

npm install -D tailwindcss postcss autoprefixer

After Tailwind and another package have been successfully installed, then run the following command to configure Tailwind for your theme development:

npx tailwindcss init

The tailwindcss init command creates a tailwind.config.js file. Here's what you'll see:

/** @type {import('tailwindcss').Config} */
module.exports = {
content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

Config your template path in the content section, so Tailwind CSS tracks the CSS classes. Then compile those classes in the production file.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["*.hbs","partials/*.hbs"],
  darkMode: 'class',
  theme: {
    extend: {},
  },
  plugins: [],
}

Create a main.css or dev.css and use any other file name to create the file for Tailwind directives. Then paste the following tailwind CSS directives code into the file:

@tailwind base;
@tailwind components;
@tailwind utilities;

Create the script for Tailwind CSS to check all the classes then create a production-ready CSS file for your theme.

    "scripts": {
        "start": "npx tailwindcss -i ./assets/css/dev.css -o ./assets/build/css/build.css --watch"
    },

The last step is to link the production-ready CSS file to your theme like this:

<head>
    {{!-- link production ready css file  --}}
    <link rel="stylesheet" href="{{asset 'build/css/build.css'}}" />
</head>

The one problem you might face when you enable Tailwind CSS in a Ghost theme is that refreshing your site in the development process is manual. When you change anything related to Tailwind classes, you'll need manually refresh your website again. I haven't found a solution yet, but you can use the live server for that for now.

Other Important Commands in the Ghost CLI

There are a number of other commands you'll use often when working in the Ghost CLI. Let's go through them now. Here's what we'll discuss:

1. ghost stop
2. ghost ls
3. ghost doctor
4. ghost uninstall
5. ghost version
6. ghost restart
7. ghost update
8. ghost version
9. ghost --help

How to use the ghost stop command

The ghost stop command stops the currently running instance.

How to use the ghost ls command

The ghost ls command prints the current installs instance list in your machine.

How to use the ghost doctor command

The ghost doctor command checks the system's health to see if everything is fine before running the ghost install or ghost update command.

If you face any errors in Ghost, you can also use the ghost doctor command to check the errors.

How to use the ghost uninstall command

The ghost uninstall command removes the Ghost instance and related configuration files as well.

How to check the Ghost version

You can use the ghost version command to check your currently installed version of Ghost.

How to use the ghost restart command

The ghost restart command restarts your currently running Ghost instance.

How to use the ghost update command

The ghost update command updates your old Ghost version to the new version.

How to use the ghost --help command

The ghost --help command prints a help page:

Finally, we'll write the code

Now we get to start writing the code. Here's what we'll cover in the coming sections:

1. How to add theme configuration in package.json [required]
2. How to use theme helpers
3. What is the partials folder?
4. How to create a default page
5. How to create an index page [required]
6. How to create a posts page [required]
7. How to create informational page
8. How to create a tags page
9. How to set up comments
10. How to enable search

How to add theme configuration in package.json

The package.json file is the main file where you add or change the theme name, description, and custom configuration for the theme.

The first step is to create package.json file and add the theme name, description, version, and additional configuration.

The following properties are used by Ghost themes: name, description, version, engines, card_assets, license, author, keywords, screenshots, and config in the package.json file.

The most important properties are name, description, version, engines, card_assets, and config. Here's what this looks like in the code:

{
    "name": "fastest",
    "description": "Fastest ghost cms base theme. Fastest is light weight, modern open-source theme",
    "version": "1.0.7",
    "engines": {
        "ghost": ">=5.0.0"
    },
    "license": "MIT",
    "scripts": {
        "dev": "gulp",
        "start": "npx tailwindcss -i ./assets/css/dev.css -o ./assets/build/css/build.css --watch"
    },
    "author": {
        "name": "Rajdeep Singh",
        "email": "officialrajdeepsingh@gmail.com",
        "url": "https://officialrajdeepsingh.dev"
    },
    "keywords": [
        "ghost",
        "theme",
        "blog",
        "light weight",
        "ghost-theme"
    ],
    "screenshots": {
        "desktop": [
            "assets/dark.png",
            "assets/light.png"
        ],
        "mobile": "assets/mobile.png"
    },
    "config": {
        "posts_per_page": 10,
        "card_assets": true,
        "image_sizes": {},
        "custom": {
            "linkedin_url": {
                "type": "text",
                "default": "None"
            },
            "github_url": {
                "type": "text",
                "default": "None"
            },
            "instagram_url": {
                "type": "text",
                "default": "None"
            },
            "copyright": {
                "type": "text",
                "default": "Copy right by Rajdeep Singh"
            },
            "copyright_url": {
                "type": "text",
                "default": "https://officialrajdeepsingh.dev/pages/terms-and-conditions/"
            },
            "adsense_enable": {
                "type": "select",
                "options": [
                    "Disable",
                    "Enable"
                ],
                "default": "Disable"
            }
        }
        },
    "devDependencies": {
        "@tailwindcss/typography": "^0.5.8",
        "autoprefixer": "^10.4.13",
        "cssnano": "^5.0.17",
        "gscan": "^4.22.0",
        "gulp": "4.0.2",
        "gulp-autoprefixer": "^8.0.0",
        "gulp-concat": "^2.6.1",
        "gulp-cssnano": "^2.1.3",
        "gulp-livereload": "4.0.2",
        "gulp-sourcemaps": "^3.0.0",
        "gulp-uglify": "^3.0.2",
        "postcss": "^8.4.20",
        "tailwindcss": "^3.2.4"
    }
}

You can learn more about card_assets and config for the theme. The config section helps add configuration for Ghost. You can also add more custom configuration for Ghost and enable and disable it with the Ghost UI.

To check all configurations, go to Ghost > Settings > Design > and click Site-wide. There you can check all configuration lists provided by the theme developer.

custom config enable and disable in ghost cms

How to Use Theme Helpers

The Ghost team provide lots of helpful functions to add additional functionality to the Ghost theme with handlebars. Some of the functionality by default comes with handlebars and other functionality is built by the Ghost team and maintained by the community.

The Ghost team uses handlebars to build the entire Ghost CMS and theme. Basically, handlebars.js is a template language that helps you build both static and dynamic websites.

There are lots of Ghost helpers like foreach, get, if, is, match, @config, comments, navigation, post, total_members, total_paid_members, block, asset, ghost_head, ghost_foot, pagination, partials, body_class, block, search and many more.

You can read about all of the helpers on the official docs. You can also copy-paste some of the code so you do not need to remember.

What is the Partials Folder?

The partials folder is like a component folder where you define all components for your theme. Basically, components are reusable code that you can reuse as often as you need. In the theme structure, we call these partials. All the partials are created with handlebars.js.

partials for ghost theme

I create more than 24 partials for my Ghost theme and you can easily reuse them across websites. You can use partials with the following syntax: {{> your-partials-file-name}}.

How to Create a Default Page

First, we need to built a default.hbs file. The default.hbs file helps us build a layout for the website. Here's the code:

<!DOCTYPE html>

<html class="dark scroll-smooth overflow-x-hidden" lang="{{@site.locale}}">

<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    {{!-- link production ready css file  --}}
    <link rel="stylesheet" href="{{asset 'build/css/build.css'}}" />
   {{!-- ghost header --}}
      {{ghost_head}}

</head>


<body class="{{body_class}} bg-white dark:bg-slate-800 dark:text-white antialiased scroll-smooth ">

  {{!-- partials/header --}}
    {{> header}}

    <main class="mt-6 flex flex-col">

{{!-- Render other pages  --}}
        {{{body}}}

    </main>
{{!-- partials/footer --}}
    {{> footer}}
    {{> banner}}

{{!-- ghost header --}}
    {{ghost_foot}}

    <script src="{{asset 'build/js/main.js'}}"></script>

</body>

</html>

Let's see what's going on here:

1. {{meta_title}} provides the title from the website.
2. The @site is a global variable and you can access a title with {{@site.title}}.
3. Include a Ghost {{ghost_head}} in the head tag.
4. Include a Ghost {{ghost_foot}} in the footer tag.
5. Inserted all other templates with the {{{body}}} tag in index.hbs, post.hbs, and so on.
6. All other templates get inserted in index.hbs, post.hbs, and so on.
7. Include dynamic CSS classes with {{body_class}} in the <body> tag
8. Add footer partials in the default {{> footer}} file
9. Add header partials in default {{> header}} file
10. Include assets from the {{asset "build/tailwind.css"}} folder.

How to Create an Index Page

Create index.hbs in the Ghost theme

The index page is the main page of the website. You can create a similar index page with the following code:

{{!--  Add default.hbs layout file --}}
{{!< default}} 

{{!-- loop all the posts and show on home page --}}

{{#foreach posts}} 

{{!--  check condition defined in config section in package.json and add adsense code after every third post --}}
    {{#has number="nth:3" }} 
        {{#match @custom.adsense_enable "Enable" }} 
            {{> ads}}
        {{/match}}
    {{/has}}

    {{!-- partials/postCard.hbs --}}
    {{> postCard }}

    {{/foreach}}

    {{!-- Add pagination --}}
    {{pagination}}

{{!--  check condition defined in config section in package.json and add adsense --}}
    {{#match @custom.adsense_enable "Enable"}}
        {{> ads}}
    {{/match}}

{{!-- newsletter partials --}}
    {{> newsletter}}

You can access all posts with a for each loop and pass them to the partials with the {{> postCard}} template. The @custom.adsense_enable is a custom config written in the package.json file and used in the theme to check that the website owner has enabled AdSense on-site or not. The custom config enables you to go to Ghost > Settings > Design > and to click on Site-wide and enable Adsense.

How to Create a Posts Page

Create post.hbs in the Ghost theme

The posts page is where readers will read your articles on your site. You can create a posts page with the following code.

{{!< default}}

{{#post}}


{{!-- Pass reading_time time to authors partials with block , learn more about about block https://ghost.org/docs/themes/helpers/block/ --}}
{{#contentFor "fastestReadingTime"}}

 <p class="text-slate-600 dark:text-slate-400 text-xs xs:text-xs sm:text-xs md:text-sm lg:text-sm xl:text-sm 2xl:text-sm ">
    {{reading_time}}
 </p>

{{/contentFor}}

{{#match @custom.adsense_enable "Enable"}}

    {{> ads}}

{{/match}}

<article class="{{post_class}} w-6/6 p-2">

    <!-- Heading section -->

    <div class="m-auto mb-4 w-6/6 xs:w-5/6 sm:w-5/6 md:w-5/6 lg:w-5/6 xl:w-5/6 2xl:w-5/6">
        <h1 class="mt-8 text-3xl xs:text-4xl sm:text-5xl md:text-5xl xl:text-5xl 2xl:text-5xl">
             {{title}} 
        </h1>
        <p class="text-slate-600 dark:text-slate-500 mt-2 text-1xl">
            {{excerpt}}
        </p>
    </div>

    <!--  Author card partials/authors -->
    {{> authors}}



    <!-- article thumbnail with partials/authors -->
    {{> featureImage}}


    <!-- article body -->
    <div class="prose-lg prose-neutral m-auto p-2 my-10 w-10/12">
        {{content}}
    </div>




</article>


    {{!-- partials/comment --}}
    {{> comment}}


{{!-- Add adsense  --}}
{{#match @custom.adsense_enable "Enable"}}

    {{> ads}}

{{/match}}

{{!-- Show related posts --}}
{{#get "posts" filter="authors:{{primary_author.slug}}+id:-{{id}}" limit="3" include="authors"}}

{{!-- if post is available then show it --}}
{{#if posts}}

<h2 class="mt-10 m-auto text-left w-5/6 text-xl xs:text-1xl sm:text-3xl md:text-4xl xl:text-5xl 2xl:text-6xl">
    Read more
</h2>

{{!-- loop all post --}}
{{#foreach posts}}
    {{> postCard }}
{{/foreach}}

{{/if}}

{{/get}}

{{!-- Add adsense  --}}
{{#match @custom.adsense_enable "Enable"}}

    {{> ads}}

{{/match}}

{{/post}}

{{!-- newsletter partials --}}
{{> newsletter}}

The fastestReadingTime block is to pass the reading time to the author partials. The @custom.adsense_enable is a custom config written in the package.json file and used in the theme to check that the website owner has enabled AdSense on-site or not. The custom config enables you to go to Ghost > Settings > Design > and to click to Site-wide and enable Adsense.

How to Create Informational Pages

Create page.hbs in the ghost theme

The page.hbs file helps you create informational pages for your website. For example, you can create an about, contact, privacy policy, or disclaimer page on your site.

{{!< default}} 

{{#post}} 

    {{!--Pass reading_time time to authors partials with block , learn more about about block https://ghost.org/docs/themes/helpers/block/     --}}
    {{#contentFor "fastestReadingTime"}}

    <p class="text-grey-600 text-xs xs:text-xs sm:text-xs md:text-sm lg:text-sm xl:text-sm 2xl:text-sm ">
        {{reading_time}}
    </p>
    {{/contentFor}}

{{!-- Add adsense base of if enable on theme  --}}
    {{#match @custom.adsense_enable "Disable"}}

        {{> ads}}

    {{/match}}

    <article class="{{post_class}}  w-6/6 p-2">

        <!-- Heading section -->
        <div class=" m-auto mb-16 w-6/6 xs:w-5/6 sm:w-5/6 md:w-5/6 lg:w-5/6 xl:w-5/6 2xl:w-5/6">
            <h1 class="text-gray-800 mt-8 text-3xl xs:text-4xl sm:text-4xl md:text-5xl xl:text-6xl 2xl:text-8xl">
                {{title}}
            </h1>
            <p class="text-gray-600 text-xl xs:text-xl sm:text-xl md:text-1xl xl:text-2xl 2xl:text-2xl">
                {{excerpt}}
            </p>
        </div>

        <!--  partials/authors -->
        {{> authors}}


        {{!--  partials/featureImage  --}}
        {{> featureImage}}



        <!-- article body -->
        <div class=" prose-xl prose-neutral m-auto p-2 my-10 w-10/12">
            {{content}}
        </div>



    </article>


    {{!-- Add adsense  --}}
    {{#match @custom.adsense_enable "Disable"}}

        {{> ads}}

    {{/match}}

    {{/post}}

The fastestReadingTime block is to pass the reading time to the author partials. The @custom.adsense_enable is a custom config written in the package.json file and used in the theme to check that the website owner has enabled AdSense on-site or not. The custom config enables you to go to Ghost > Settings > Design > and to click to Site-wide and enable Adsense.

How to Create an Author Page

Create author.hbs in the ghost theme

Author pages let you describe the author. You can show the author's name, bio, and related articles.

{{!< default}}

{{#author}}

{{!--  Author Section pass with block learn more about about block https://ghost.org/docs/themes/helpers/block/ --}}
   {{#contentFor "authorName"}}
      {{name}}
    {{/contentFor}}

<div class="container mt-20 mb-16 flex flex-col justify-between mx-auto">

    <div class="flex flex-col mt-6 w-6/6 xs:w-5/6 sm:w-5/6  md:w-3/6 lg:w-3/6 xl:w-3/6 2xl:w-3/6 xs:mt-6 sm:mt-6 md:mt-6 lg:mt-0 xl:mt-0 2xl:mt-0 ">

        <h1 class="text-3xl mt-5 xs:text-3xl sm:text-3xl md:text-4xl xl:text-5xl 2xl:text-6xl"> {{name}} </h1>

        {{#if bio}}
            <p class="mt-0 xs:mt-0 sm:mt-0 md:mt-1 lg:mt-3 xl:mt-3 2xl:mt-3 text-md">
                {{bio}}
            </p>
        {{/if}}

        <ul class="flex flex-row my-3">

            <li class="text-md">{{location}}</li>

               {{#if facebook}}

                    <li class="mx-3 text-sm flex items-center">
                        <a target="_blank" href="https://facebook.com/{{facebook}}" >

                        {{!-- Pass partials/Icons/facebook --}}
                            {{> Icons/facebook}}

                        </a>
                    </li>

                {{/if}}
                {{#if twitter}} 
                    <li class="mx-3 text-sm flex items-center">
                        <a target="_blank" href="https://twitter.com/{{twitter}}" >

                        {{!-- Pass partials/Icons/twitter --}}
                            {{> Icons/twitter}}

                        </a>
                    </li>
                {{/if}}
                {{#if website}} 
                    <li class="mx-3 text-sm flex items-center">
                        <a target="_blank" href="{{website}}" >

                            {{!-- Pass partials/Icons/website --}}
                            {{> Icons/website}}

                        </a>
                    </li>
                {{/if}}
        </ul>
    </div>
</div>


{{!--  get posts related to author base on author Id --}}
    {{#get "posts" limit="all" filter="authors:{{slug}}+id:-{{id}}" order="published_at desc"   }}

        {{#if posts}}
                {{#foreach posts}}
                    {{> authorCard}}
                {{/foreach}}
        {{/if}}

    {{/get}}

{{/author}}

How to Create a Tags Page

Create tag.hbs in the ghost theme

You can use the tag.hbs file to show articles related to the tag used.

{{!< default}}


{{#tag}}

<div class="container m-auto mt-32  mb-16  w-5/6 xs:w-5/6 sm:w-5/6 md:w-5/6 lg:w-5/6 xl:w-5/6 2xl:w-5/6">

    <h1 class=" text-gray-800 text-4xl xs:text-5xl sm:text-6xl md:text-7xl xl:text-8xl 2xl:text-9xl">{{name}}</h1>

    {{#if description}}
        <p class=" text-gray-600 text-xl xs:text-xl sm:text-xl md:text-1xl xl:text-2xl 2xl:text-2xl">
            {{description}}       
        </p>
    {{/if}}


</div>

{{!--  get posts related to tag base on  tag slug --}}

    {{#get "posts" include="authors,tags" limit="3" filter="tag:{{slug}}" as |related|}}

   {{!-- loop posts base on article --}}
        {{#foreach related}}

    {{!--  check condition define in config section in package.json and add adsense code after every third post --}}
            {{#has number="nth:3"  }}
                {{#match @custom.adsense_enable "Enable"}}
                    {{> ads}}
                {{/match}}
            {{/has}}

        {{!-- partials/postCard.hbs --}}
            {{> postCard }}

        {{/foreach}}

    {{/get}}

{{/tag}}

How to Create an Error Page

Create error.hbs in the ghost theme

You use the error.hbs file to show when any errors occur on the website. Error pages help your website not break in production. The most common error is a 404 (not found) error.

{{!< default}} 
<div class="flex flex-col m-auto p-10 w-5/6 xs:w-5/6 sm:w-5/6 md:w-5/6 lg:w-5/6 xl:w-5/6 2xl:w-5/6">
    <h1 style="font-size: 10.8rem;" class="text-black text-center">
        {{statusCode}}
    </h1>

    <p class="text-4xl -m-6 text-center">
        {{message}}
    </p>

    <a href="/" class="text-center w-32 m-auto my-20 p-3 bg-black text-white items-center rounded-full">
        Home
    </a>
</div>

How to Enable Comments

enable comments in the ghost theme

Ghost 5 officially supports the commenting system (it's built-in) and you can just enable comments on the theme by copying and pasting the code – you never need any configuration. Ghost itself handles all the configurations. Here's the code:

<div class="m-auto my-8 w-10/12">
    <p class="text-right text-xs xs:text-xs sm:text-xs md:text-sm lg:text-sm xl:text-sm 2xl:text-sm ">
        Before comment read our <a style='text-decoration: underline' href="https://officialrajdeepsingh.dev/terms-and-conditions/">term and condition </a>
    </p>
    <div class="mt-5 mb-5 p-4">

   {{!--  Enable comment on theme --}}
       {{comments}}
    </div>
</div>

How to Set Up Search

enable the search bar in the ghost theme

Ghost 5 comes with the official support of search functionality. You do not need any other configuration. Just paste the following code into your theme and the search functionally will start working on your site.

{{!-- partials/Icons/search --}}
<button class="gh-search" data-ghost-search>{{> Icons/search}}</button>

Conclusion

Building a theme with Ghost is a relatively straightforward process compared to WordPress. The Ghost team has created well-defined documentation that you can easily follow as a beginner with examples.

They also provide many ready-made components, like search functionality, amp page, comments, and so on.

You can create your Ghost theme by copy-pasting the code. For beginner developers, it might seem a bit complicated, but you'll get the hang of it with some time and work.

The Ghost team has created a well-defined folder structure for theme development. It is the easiest way to manage the theme development process. You can also use npm packages to enhance the development process and add more functionality to the theme. In my theme, I use tailwind CSS and the Gulp package to speed up the development process.

Lume is not built around any specific language. It supports Markdown, Nunjucks, TypeScript, and JavaScript by default. Lume also supports plugins. Some plugins come preinstalled by default. This is why Lume itself is template-language agnostic.

Before learning more about Lume, let's discuss Deno and consider some important Deno features.

What is Deno?

Deno is an alternative to Node.js built by Ryan Dahl (who also developed Node). Deno is based on the Rust programming language, and the second main component in Deno is the JavaScript V8 engine for WebAssembly.

Deno has many cool features – it's fast, secure by default, is compatible with web assembly and has TypeScript support, has in-built development tools, and more. Deno also supports Node.js APIs so you can use all npm packaged with Deno.

In Deno, you do not need to create a configuration file to run a simple program. You simply deploy your website instantly with a second on-edge network. But my final favorite feature is the new node_modules folder in the workspace. Deno caches all the packages locally and uses them, which is very fast compared to Node.

You can check out the demo blog website here, and all the code is available on GitHub here.

Now let's dive into the tutorial.

Table of Contents

1. Lume + Markdown
2. Why is Lume special?
3. How does Lume compare to other static site generators?
4. How to start a new project with Lume
5. Lume folder structure
6. Additional folders
7. How to create global data
8. How to create a dynamic page
9. How to create a Home and Pagination page
10. How to build an articles page
11. How to generate a category page
12. How to generate a tag page
13. How to enable search functionality
14. How to install page find
15. Lume SEO
16. Lume Sitemap
17. Lume plugins
18. How to enable comments
19. How to use Netlify CMS with Lume
20. How to deploly your blog with Deno Deploy
21. Github pages
22. Conclusion

Lume + Markdown

Lume is a new static site generator based on Deno created and maintained by Óscar Otero. Lume uses markdown-it as the default markdown. You can use the remark plugin to change the default markdown.

Markdown is a language that helps to write documents, readme files, and blogs on the internet. John Gruber created markdown in 2004.

Markdown-it is similar to GitHub-flavored Markdown (GFM) markdown. GFM and markdown-it both follow the exact markdown specifications.

If you've worked with GitHub and written README files, that means you are likely familiar with GFM markdown. If you don't like the default (markdown-it) markdown, you can change the markdown with the remark plugin.

There are tons of static site generators. So why is Lume special? What does it provide compared to other static site generators? Let's find out.

Why is Lume special?

As you know, Lume is built on Deno, and Deno is a Node.js alternative—that is why Lume provides lots of features out of the box.

Lume works similarly to a GitHub readme file. If you're familiar with writing one of those (and using markdown), you do not need to learn anything else to write articles and documentation with Lume.

Here are some benefits of Lume:

1. Lume supports multiple template engines like Markdown, Nunjucks, Eta, JSX, Liquid, or Pug.
2. It supports multiple authors
3. It has code syntax highlighting
4. There's great SEO support
5. Lume supports multiple languages
6. It has Windi CSS support
7. There's pagination and component support
8. It supports minifying JavaScript, HTML, CSS, and SASS
9. It has relations support
10. There is the built-in search functionality
11. It supports Netlify CMS
12. It supports images and SVGs
13. There's Remark.js plugin support
14. You can deploy with Netlify, Vercel, GitLab Pages, and the GitHub page.

How Does Lume Compare to Other Static Site Generators?

Lume is a new static site generator compared to others, but it comes with many configuration options, and you can do anything with it. You don't even need to use any third-party plugins.

With Lume processors and preprocessors, you can easily manipulate the HTML code with the JavaScript DOM API. Other static site generators support a few template engines, but Lume supports many template engines like JavaScript, JSX, Nunjucks, Eta, JSX, Liquid, and Pug.

Note that Lume can seem tough to get started with for beginners. But if you're following my article, just make sure to open the code which will make things much clearer for you.

How to Start a New Project with Lume

You can set up a new project with the Lume CLI with this command:

deno run -Ar https://deno.land/x/lume/init.ts

Lume installation demo

Follow these steps:

1. First, create an empty mkdir lume-deno folder project.
2. Then run the lume init.ts command.
3. Select an available plugin from the list.

And you should be up and running.

Lume Folder Structure

After the installation finished, we saw three files:

1. _config file is used to configure Lume.
2. deno.json is a defined script or task for Deno.
3. import_map.json is to help you import a Deno package for the internet.

lume default folder structure

How to run the Lume server

To run a local development server, you'll use the deno task lume --serve command. To build a website, run the deno task build command.

If you face a 404 - not found error, you can create a index.njk file within the root folder.

In the index.njk file, paste the following code.

---
title: "hello"
---
hello world

And you'll see the following output:

Lume hello-world

Additional folders:

1. posts folder is not a compulsory folder. It contains all your posts' markdown files.
2. pages folder is not a compulsory folder. It has all your pages' markdown files.
3. author folder is not a compulsory folder. It has all your author markdown files.
4. _components folder is a compulsory folder. It has all your components.
5. _includes folder is a compulsory folder. It contains your layout and templates for your site.
6. images folder is not a compulsory folder. It contains all your images.

The posts, pages, authors, and images folders are optional. You can rename these folders according to your wishes. The _components and _includes folders are mandatory and you don't rename them.

The difference between components, layout, and template are as follows:

• The components are reusable code
• The layout and template are not reusable like components.

How to Create Global Data

In Lume, you can create a data variable, which has access to the entire website by all template engines.

// Set a variable
site.data("post_per_page", 10);

// Set a function
site.data("randomNumber", function () {
  return Math.random();
});

How to create posts, pages, and author markdown files

You create posts, pages, and author folders in the root folder. Then, inside every folder, you write markdown files.

You can access all posts, pages, and authors by file name on the browser:

1. localhost:3000/posts/your-title.html
2. localhost:3000/pages/your-pages.html
3. localhost:3000/author/your-author.html

Suppose you need a demo post, pages, and author markdown for a project or template. Then, you can use demo-markdown posts for your project. It is free and open source, and you can create your own template.

How to create a dynamic page

In Lume, .tmpl.js and .tmpl.ts extensions use JS and TS as template engines. You can use them with regular pages or dynamic pages to create categories, tags, pagination, and so on for your website.

How to create a home and pagination page

The home page is based on pagination, and pagination is based on posts. Lume dynamically generates the pagination.

In Lume, I chose nunjucks and JavaScript to create my demo website. Nunjucks is the default template engine. You can easily change the default Nunjucks engine with another template engine with copy-paste code.

home page

Lume provides a JavaScript template function that helps create dynamic web pages. If you create a home page for the site, you need to create an index.tmpl.js file in your root or src folder. Lume also supports an src folder to organize your project. In my demo project, I'm not using the src folder.

The *.tmpl.js is an extension of a JavaScript template that helps create dynamic pages for websites. It comes pre-installed in Lume with the modules plugin.

For example, the following code creates pagination for your website. But the layout comes from the _includes folder.

// index.tmpl.js

// title for SEO
export const title = "Minimalist blog"
// description for SEO
export const description = "Minimalist blog theme is liteweight and work with lume."

export default function* ({ search, paginate }) {

//  Get all posts of type article.
  const posts = search.pages("type=article", "date=desc");

  // Configation for pagination
  const options = {
    // Page 1 is the homepage, set "/" as url
    url: (n) => n === 1 ? "/" : `/page/${n}/`,
    // par page posts
    size: 7,
  };

  // Yield the pages, but the index needs a different layout
  for (const page of paginate(posts, options)) {

    //  if home page, use diffrent layout "/"
    if (page.pagination.page === 1) {
      page.menu = {visible: true, order: 1, title:"Home" }
      page.title = "Home page"

      //  comes from _includes folder

      page.layout = "layouts/home.njk";
    } else {
      // Render diffrent layout if it is not home page page "/page/2","/page/3",etc
      page.title = "Pagination page"

      page.layout = "layouts/home.njk";
    }

    yield page;
  }

}

‌Lume has a search plugin that helps you search pages. In my demo blog, I search all pages base on the type.

In my all posts folder, all posts are defined in type=article, the author is described in type=author, and pages are defined in type=page . The search plugin is pre-installed with Lume.

On index.tmpl.js file, you can get all pages that have the type "article" (type=article ) using the following code: const posts = search.pages("type=article", "date=desc");. The search.pages("type=article", "date=desc") function only returns those that have type=article .

The layouts/base.njk layout file contains an HTML base and includes a header and footer for the website.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
    <meta name="description" content="{{ description or site.description }}">
   </head>
  <body>

    {% include "layouts/header.njk" %}

    <main class="{{ bodyClass }}">
      {{ content | safe }}
    </main>

    {% include "layouts/footer.njk" %}

  </body>
</html>

Inside the {{ content | safe }}, Lume renders other HTML, like cards, articles, home templates, Tag and category pages, and so on.

// rest code ...
  for (const page of paginate(posts, options)) {
  }
// rest code ...

I used the for loop on the index.tmp.js file that helps get all the posts and send them to the layouts/home.njk file and the layouts/home.njk file. You get all posts from the result, and then pass them to the card.njk template.

---
layout: layouts/base.njk
---

{% for post in results %}
    {% include "templates/card.njk" %}
{% else %}
    <h2> Posts is empty </h2>
{% endfor %}

{% include "templates/pagnation.njk" %}

‌The templates/card.njk file runs for all blogs and generates HTML for each blog. Your card looks like this:

card.njk

In card.js template, you can access it using {{}} curly brackets. Get the title using {{post.data.title}} and {{post.data.description}}.

In my demo blog, I'm getting only the first category to show inside the card. So I use a defined filter _config.ts and use it with | symbols. Inside card.njk we get a zero index or first value in from categories with the following code: {{ post.data.category | category }}.

To get the author on card.njk I define the relationship between the article and the author type, which you can learn about from the docs.

<div class="container px-6 py-10 mx-auto">

    <div class="mt-8 lg:-mx-6 lg:flex lg:items-center">

        <img class="object-cover border-none w-full lg:mx-6 lg:w-1/2 rounded-xl h-72 lg:h-96" src="{{ post.data.image }}" alt="{{ post.data.title }}">

        <div class="mt-6 lg:w-1/2 lg:mt-0 lg:mx-6 ">

            <a class="text-sm text-blue-500 uppercase" href="/category/{{ post.data.category | category }}" >
                {{ post.data.category | category }}
            </a>

            <a href="{{ post.data.url }}" class="block mt-4 text-2xl font-semibold text-gray-800 hover:text-gray-500 dark:text-white md:text-3xl">{{ post.data.title }}</a>

            <p class="mt-3 text-sm text-gray-500 dark:text-gray-300 md:text-sm">
                {{ post.data.description }}
            </p>

            <a href="{{  post.data.url }}" class="inline-block p-2 bg-blue-700 mt-4 text-white hover:bg-blue-500">Read more</a>


            <div class="flex items-center mt-6">

                {% if post.data.author.length <= 2 %}

                    {% for author in post.data.author %}

                        <img class="border-none object-cover object-center w-10 h-10 rounded-full" src="{{ author.image}}" alt="{{ author.author_name}}">

                        <div class="mx-4">
                            <a href="{{author.url}}" class="text-sm text-gray-700 dark:text-gray-200">
                                {{ author.author_name}}</a>
                            <p class="text-sm text-gray-500 dark:text-gray-400">
                                {{author.job}}
                            </p>
                        </div>
                    {% endfor %}
                {% else %}

                    <img class="border-none object-cover object-center w-10 h-10 rounded-full" src="{{ post.data.author.image}}" alt="{{ post.data.author.name}}">

                    <div class="mx-4">
                        <a href="{{ post.data.author.url}}" class="text-sm text-gray-700 dark:text-gray-200">
                            {{ post.data.author.author_name}}</a>
                        <p class="text-sm text-gray-500 dark:text-gray-400">
                            {{post.data.author.job}}
                        </p>
                    </div>
                {% endif %}

            </div>
        </div>
    </div>
</div>

The {{ title }} and {{description}} both show the markdown file title and description. To show the category, I used a filter to show a single category on the article page and define the filter on _config.ts file. I also show single and multiple authors with For loop. Every card has its own post.data.url property, after the user clicks on the read more button user ago respected the article read page. To show the image, I used {{ post.data.image }} property. I also show single and multiple authors with For loop on card.njk file.

How to Build an Articles Page

I know the page containing the article content is one of the most important for a blog. It's where readers should spend most of their time rather than the website's home page.

---
category:
  - Blog
date: 2022-03-20T13:09:24Z
description: Dolor excepteur ad ad fugiat Lorem consectetur velit excepteur duis qui.
image: /images/dice.jpg
tags:
  - npm
  - npm cli
  - npm install command
title: Random blog Title for markdown.
draft: false
author_id: 1
type: article
layout: templates/article.njk
---

Laboris consequat elit ad excepteur. Ipsum duis amet dolore voluptate dolore consequat ullamco incididunt ullamco. Dolore laborum cupidatat dolor ipsum reprehenderit excepteur cupidatat dolore.

## First
Cupidatat non amet irure esse quis aute qui enim. Est qui ullamco proident consequat aute reprehenderit eiusmod nisi. Laboris ullamco fugiat sint occaecat.

## Second 
Irure fugiat officia non esse esse irure eu sint commodo quis amet. Dolor culpa non amet elit adipisicing exercitation ex anim velit ipsum.

## conclusion
Culpa irure eiusmod labore ut proident sit enim laborum nulla voluptate eu. Id tempor velit cillum pariatur est laboris ipsum ad. Sint nostrud nostrud laboris Lorem consequat tempor voluptate dolore velit. Commodo elit nulla commodo pariatur. Deserunt ipsum fugiat id ipsum pariatur cupidatat magna ex. Fugiat aliquip nisi laboris aliquip velit velit id quis eu reprehenderit excepteur fugiat.

I created an article in the posts folder under type=article . The author_id defines the relation between the author and the article.

I used templates/article.njk as the layout for my articles page. You can design yours as per your requirements. You can design the article title, description, author card, and tags as well.

---
layout: layouts/base.njk
---
<article class="container mx-auto p-2">
  <div class="flex flex-col">

    <h1 class="text-2xl text-black mt-3">{{ title }}</h1>
    <p class="text-xl mt-1 text-gray-600">{{ description }}</p>

    {% if author %}
      <div class="flex flex-row mt-4">


        {% if author.length <= 2 %}

          {% for author in author %}

            <img class="border-none object-cover object-center w-10 h-10 rounded-full" src="{{ author.image}}" alt="{{ author.author_name}}">

            <div class="mx-4">
              <a href="{{author.url}}" class="text-sm text-gray-700 dark:text-gray-200">
                {{ author.author_name}}</a>
              <p class="text-sm text-gray-500 dark:text-gray-400">
                {{author.job}}
              </p>
            </div>
          {% endfor %}

        {% else %}

          <img class="border-none object-cover object-center w-10 h-10 rounded-full" src="{{ author.image}}" alt="{{ author.name}}">

          <div class="mx-4">
            <a href="{{ author.url}}" class="text-sm text-gray-700 dark:text-gray-200">
              {{ author.author_name}}</a>
            <p class="text-sm text-gray-500 dark:text-gray-400">
              {{ author.job}}
            </p>
          </div>
        {% endif %}

      </div>

    {% endif %}

      <nav class="flex flex-row my-5">
        {% for tag in tags %}
          <a href="/tag/{{ tag.trim().toLowerCase().split(' ').join("-") }}/" class=" bg-blue-500 text-black p-2  mx-1">{{ tag }}</a>
        {% endfor %}
      </nav>

    <time class="mt-2" datetime="{{ date | date('DATETIME') }}">
      {{ date | date('HUMAN_DATE') }}
    </time>


  </div>

  <div class="mt-4">
    {{ content | safe }}
  </div>
</article>

{%- set previousPost = search.previousPage(url, "type=article") %}

{% if previousPost %}
  <ul class="flex flex-row w-full mt-10 justify-between p-4">
    {%- if previousPost %}
      <li class="w-6/12 text-left">
      ← Previous: <a href="{{ previousPost.data.url }}" rel="prev">{{ previousPost.data.title }}</a>
      </li>
    {% endif %}

    {%- set nextPost = search.nextPage(url, "type=article") %}
    {%- if nextPost %}
      <li class="w-6/12 text-right">
        <strong>Next: <a href="{{ nextPost.data.url }}" rel="next">{{ nextPost.data.title }}</a> →</strong>
      </li>
    {% endif %}
  </ul>
{% endif %}

<div class="container p-2 mx-auto mt-6"> 

{# ==== #}
{#  Addding the utteranc Commenting script #}
{# ==== #}

<h1 class="text-center text-2xl my-3"> Comment </h1> 

<script src="https://utteranc.es/client.js"
        repo="officialrajdeepsingh/Minimalist-blog"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>
</div>

The layouts/base.njk file is the base file for our blog (which I've already explained). The {{ title }} and {{description}} both show the markdown file title and description.

To show tags on the article page, I used a for loop. I also showed single and multiple authors with the for loop.

To convert the date into a human-readable format, I used Lume date plugin and wrapped it with a date filter that looks like this: {{ date | date('HUMAN_DATE') }}. To show all markdown paragraphs, I used {{ content | safe }} .

For pagination, I used the Lume pagination plugin, and with the search.previousPage(url, "type=article") function, I showed the next and previous posts on the article page. For comments, I used utteranc.es.

How to Generate a Category Page

In Lume, you create a dynamic category based on article type. Lume also provides inbuilt functionality called a JavaScript template engine that helps you create a dynamic page. It is similar to creating pagination functionality.

In Lume, there's a special file called .tmpl.js that helps you create a dynamic category.

export const layout = "layouts/category.njk";

export default function* (props) {


  const { search }= props

  for (const category of search.values("category") ) {

    yield {
      url: `/category/${category}/`,
      title: `Categoryed ${category}`,
      type:"category",
      category,
    };

  }

}

In lume search.values() have a function that helps you find a category using markdown meta tags and sends data into the layout/category.njk file. It will generate all categories with the following URLs like /category/android/ , /category/android-phone/ , /category/human/ and so on.

How to Generate a Tag Page

Generating a dynamic tags page is similar to a category. Lume provides a special search.tags() function to generate tags:

export const layout = "layouts/tag.njk";

export default function* ({ search }) {

  for (const tag of search.tags()) {
    yield {
      url: `/tag/${tag}/`,
      title: `Tagged ${tag}`,
      type: "tag",
      tag,
    };
  }
}

The following code generates all tags with the following URLs like /tag/android/, /tag/android-phone/, /tag/human/ and so on.

How to Enable Search Functionality

Lume has many in-built plugins which provide an excellent development experience. You can solve lots of problems with Lume plugins, and they allow you to add and remove features easily.

Lume provides inbuilt search functionality for the site. You enable it with the lume page find plugin.

Add a search bar in lume

How to Install Page Find

The Lume page finds plugin provides you with a search bar. Simply copy the following code and paste it into the _config.ts file and restart your server.

import pagefind from "lume/plugins/pagefind.ts";

How to configure the page find plugin

You configure the plugin in the _config.ts fil. You can also change the default config.

// rest of code ...
import lume from "lume/mod.ts";
import pagefind from "lume/plugins/pagefind.ts";

const site = lume();

// config the pagefind plugin with default config
site.use(pagefind());

 // or 

// change the default config in pagefind plugin
site.use(pagefind({
  ui: {
    containerId: "search",
    showImages: false,
    showEmptyFilters: true,
    resetStyles: true,
  },
}));

export default site;

Lume SEO

Lume has a plugin to help with SEO called metas. With the plugin, you can easily add various SEO-friendly configurations.

How to install metas

You install all plugins within the config.ts file. Copy the following code and paste it into the config.ts file, then restart the server.

import metas from "lume/plugins/metas.ts";

How to configure metas

You can configure metas in various ways in the _config.ts file. See the comments below:

import lume from "lume/mod.ts";

// install metas plugin for SEO
import metas from "lume/plugins/metas.ts";

const site = lume();

// config the metas plugin with default config
site.use(metas());

or

// add custom config 
site.use(metas({
  defaultPageData: {
    title: "title", // Use the `title` value as fallback.
  },
}));


export default site;

How to Use the Metas SEO Plugin in Lume

To use the SEO metas plugin, you'll need to create a _data.yml file in the root of the project folder and paste the following code into it:

metas:
  site: Minimalist blog
  twitter: "@Official_R_deep"
  icon: /images/icon.png
  lang: en
  generator: true

mergedKeys:
  metas: object

The following code helps you create all the various SEO tags for your website, and you can easily extend it with the metas plugin in Lume.

Lume Sitemap

Lume has a plugin called sitemap. This plugin helps you create sitemaps for your blog. With Lume 13 you do not need to create a sitemap manually.

How to install the sitemap plugin

You install all plugins within the config.ts file. Copy the following code and paste it into the config.ts file, then restart the server.

import sitemap from "lume/plugins/sitemap.ts";

How to configure the sitemap plugin

You can configure the sitemap plugin in various ways in the _config.ts file. See the comments below:

import lume from "lume/mod.ts";
import sitemap from "lume/plugins/sitemap.ts";

const site = lume();

site.use(sitemap());

// or

// add custom config 
site.use(sitemap({
  filename: "my-sitemap.xml", // to change the sitemap filename
  query: "indexable=true", // Select only pages with the indexable attribute as true
  sort: "date=desc", // To sort by data in ascendent order
}));

export default site;

How to use the sitemap plugin in Lume

You do not need any special file to use the site map plugin. Simply add the plugin after calling the plugin in config.ts and it'll start working on your site. This creates the sitemap.xml file and you can change the file name with a custom configuration in _config.ts file.

How to access the sitemap on the website

You can access the sitemap with the filename, for example by default in the localhost [http://localhost:3000/sitemap.xml](http://localhost:3000/sitemap.xml) and production [http://my-domain-name/sitemap.xml](http://localhost:3000/sitemap.xml) .

Lume Plugins

Lume comes with inbuilt plugins, but you can easily add or remove features according to your requirements. You do not need all the stuff on your site – you can configure everything as you wish.

You can add more template engines, minify HTML, CSS, and JavaScript with plugins, enable code highlighting, date manipulation, image manipulation, SVG support, and more.

You can also easily create your own plugins with lume. Lume also provides excellent documentation where you can learn more.

How to Enable Comments

To add comments on your Lume site, I think utteranc.es is the best choice for all static site generators. utteranc.es is an open-source commenting system based on GitHub. It looks like this:

Enable comment

If you want to enable comments on the site, the first step is to install an utterances application on GitHub. Then, copy and paste the following code into the article read file or where you show comments on the site.

<script src="https://utteranc.es/client.js"
        repo="officialrajdeepsingh/Minimalist-blog"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

Next, you'll need to change the utterance comment script. The first change in the repo repo="your-github-repo" name is compulsory. The others are not. You can adjust according to your requirements – for example, changing the theme, issue term, and so on.

To read more about utterance, here's a great article written by Josh Collinsworth.

The best approach is to add utterance comments in lume and then read the GitHub discussion.

How to Use Netlify CMS with Lume

Netlify CMS is an open-source content management system. You can easily integrate Netlify with Lume using the netllify_cms plugin. It is provided by Lume, and you just need to install it and copy/paste the code.

How to Install the Netlify Plugin

Import the Netlify plugin in your _config.ts file to use it like this:

import lume from "lume/mod.ts";
import netlifyCMS from "lume/plugins/netlify_cms.ts";

const site = lume();

site.use(netlifyCMS());

export default site;

To configure it, you'll need to create a /_data/netlify_cms.yml file in the root level and then paste the following code after restarting your server:

backend:
  name: git-gateway
  branch: master

media_folder: statics

collections:
  - label: Posts
    name: posts
    description: List of posts
    folder: posts
    extension: md
    create: true
    fields:
      - label: Title
        name: title
        widget: string
      - label: Content
        name: body
        widget: markdown

Netlify will ask you for permissions for the CMS proxy. Type npx netlify-cms-proxy-server in a terminal, press enter or type y, and your Netlify CMS will start running locally on http://localhost:3000/admin URL. Now your Lume blog is ready for deployment on Netlify.

How to Deploy Your Blog with Deno Deploy

You can deploy Lume on various platforms such as Deno Deploy, GitHub Pages, Gitlab Pages, Netlify, Vercel, Fleek, AWS Amplify, and Cloudflare Pages. Lume also provides excellent documentation on deployment.

In this article, I'm deploying my Lume blog with Deno Deploy (and we'll also see how to do it with GitHub pages). Deno Deploy is an official platform built by the Deno team to deploy Deno-based applications.

Before deploying your Lume blog on Deno Deploy, make sure you create a server.ts file in the root level.

import Server from "lume/core/server.ts";

const server = new Server({
  port: 8000,
  root: `${Deno.cwd()}/_site`,
});

server.start();

console.log("Listening on http://localhost:8000");

Deployment Steps:

1. Create an account on Deno Deploy.
2. Push your local code to GitHub and then select the server.ts file. Deno Deploy automatically creates a site based on the server.ts the file.
3. Make sure to first create a custom server.ts file. Then move to the next step.
4. The easiest way to deploy your site is with GitHub Actions. Create a new .github/workflows/deno.yml file in your project root level and paste the following code into it:

name: Deploy
on: [push]

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Needed for auth with Deno Deploy
      contents: read # Needed to clone the repository

    steps:
      - name: Clone repository
        uses: actions/checkout@v3

      # TODO: add a build step here

      - name: Upload to Deno Deploy
        uses: denoland/deployctl@v1
        with:
          project: "minimalist-blog"
          entrypoint: "./serve.ts"

How to Deploy Your Blog with Github Pages

GitHub Pages are free static sites you can use to host pages. You can also deploy your Lume blog it. The process of deployment is pretty easy.

To deploy Lume on GitHub pages you need to have GitHub Actions set up.

Deployment Steps

1. It's best if you have a GitHub repository so you can convert your local website to GitHub Pages.
2. Create a new repo and push all your local code into it.
3. Create a new .github/workflows/deno.yml in your project root level, then paste the following code into it and push it into the GitHub repo. The GitHub action runs based on the github.yml action and it generates a GitHub page.

name: Publish on GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Clone repository
        uses: actions/checkout@v3

      - name: Setup Deno environment
        uses: denoland/setup-deno@v1
        with:
          deno-version: v1.x

      - name: Build site
        run: deno task build

      - name: Deploy
        uses: crazy-max/ghaction-github-pages@v3
        with:
          build_dir: _site
        env:
          GITHUB_TOKEN: ${{ secrets.MY_GITHUB_TOKEN_PAGE }}

You need a GitHub token to deploy your Lume website to GitHub pages. This is a required part of the setup. I found a great article written by Davide that can help you learn more about GitHub Actions and how to create one.

GitHub Actions takes two or three minutes to finish hosting your website on GitHub Pages.

Check out the GitHub repository to learn how to configure the GitHub workflow for GitHub pages. You can also see a live demo website on the GitHub page.

A quick note: if you deploy your Lume site on GitHub pages and your image does not show on the website, there are two possible reasons for this:

1. If all image names aren't in lowercase, you might get an error. To resolve the error, convert your image names into lowercase with this command: your.github.com/your-reponame/images/my-image.png
2. If you're using the base_path and relative_urls Lume plugins in your project and relative_urls is redundant, and then you'll need to remove the relative_urls plugin in your project. Your image should now work fine.

Conclusion

Lume is an easy-to-learn and feature-rich static site generator. You can do anything you imagine with it. Lume gives you a lot of freedom with the code.

The Lume community is not as big as those of Hugo, 11ty, Jekyll, and other tools. But, the Lume maintainers actively reply to everybody who comments in the GitHub discussion. Without a strong community, this tool should be able to create a strong impact.

One challenge with Lume is that it's tough to get started for beginners and is more suited to intermediate and advanced developers. If you're jumping right into using Lume as a beginner, you might struggle with a lack of background knowledge about how static site generators work.

Because of this, it's helpful to have a little bit of knowledge about Nuckjunks, JSX, and other template engines that work based on markdown. Once you gain this experience, then you'll easily be able to use Lume to design your markdown-based blog.

I recommend using the lume MDX plugin for markdown. You can use JSX-based components inside the markdown file, and you can create beautiful code blocks, tip blocks, and so on.

I highly encourage all developers to try Lume out. If you have problems with Lume, you can reach out to its creator on the GitHub discussion and the Discord server.

If your course is about Computer science, Bioinformatics, and Biotechnology. You can join my free newsletter.