déGit Pages Jekyll Theme

An elegant, opinionated-yet-customizable Jekyll theme, stylized after the déGit Pages homepage.



How to use

1. Add jekyll-theme-degit-pages to your site’s Gemfile.

   gem "jekyll-theme-degit-pages", git: "https://www.degit.click/deGit/degit-pages-jekyll-theme.git"
   

   If you would like to use the theme with CJK-supported fonts (adds build time and final site size), you can specify the cjk branch.

   gem "jekyll-theme-degit-pages", git: "https://www.degit.click/deGit/degit-pages-jekyll-theme.git", branch: "cjk"
   

2. Add theme: jekyll-theme-degit-pages to your site’s _config.yml.

   theme: jekyll-theme-degit-pages
   

degit_theme:
  sticky_navbar: true
  footer_extra: "Hosted on <a href='https://www.degit.page'>déGit Pages</a>"
  content_max_width: 1216 # Match Forgejo
  forgejo_header: true
  forgejo_header_full_path: false
  heading_anchors: true
  toc: true



Design tokens



Typography



Noto Serif Display

For headings and site titles, we use Noto Serif Display. This elegant serif font is free for personal and commercial use, and absolute eye candy, especially for highlighting section.



Ubuntu

For general text, we use Ubuntu. This stylish sans-serif font is free for personal and commercial use, and looks great as a general body text font.



Maple Mono

Maple Mono is the monospace font used for code blocks in the déGit Pages theme. This playful monospace font with a handwritten feel in italics is free for personal and commercial use. Based on JetBrains Mono, this rounded font is sure to catch your eye, and be a joy to read. When using the cjk branch, Maple Mono CN with CJK support from Resource Han Rounded is used instead to provide CJK Support in monospace text.



Symbols NerdFont and Symbols NerdFont Mono

NerdFonts support has been moved from using Ubuntu NF and Maple Mono NF to a separate font, so icon glyphs can be used independently from other fonts, and to slightly reduce download sizes of fonts. Neat!



Colors



Customization

As mentioned above, this theme is very customizable. This section is dedicated to all customization options available. All customizations to the theme are defined in the _config.yml file under the degit_theme key.



sticky_navbar and sticky_footer

# Default values
degit_pages:
  sticky_navbar: false # true makes the navbar stay at the top of the screen
  sticky_footer: false # true makes the footer stay at the bottom of the screen



footer_credits and footer_extra

# Default values
degit_pages:
  footer_credits: true # false hides the Jekyll link and theme credits
  footer_extra: "" # any text content is rendered as HTML - ideal for extra links, etc.



accent_hue and h1_underline

# Default values
degit_pages:
  accent_hue: 247 # 0-360
  h1_underline: true # false removes the underline from the first <h1> tag (single # in markdown)



forgejo_header and forgejo_header_full_path

# Default values
degit_pages:
  forgejo_header: false # true enables the Forgejo-style header on this page
  forgejo_header_full_path: false # true shows the full path to the current page relative to the website root



content_max_width

content_max_width changes the maximum width of the content (not including the Forgejo Header).

# Default values
degit_pages:
  content_max_width: 860 # width in pixels; 1216 combined with `forgejo_header: true` mimics Forgejo UI



Anchors and TOC

The déGit Pages Jekyll Theme bundles Pure Liquid jekyll-anchor-headings and jekyll-toc. To enable and configure them, degit_theme exposes a few configuration options.

# Default values
degit_theme:
  heading_anchors: false # true enables anchors for all headings
  anchor_body: "" # what text to insert into the anchor link
  anchor_before_heading: true # false places anchor after the heading
  anchor_min_level: 2
  anchor_max_level: 6
  toc: false # true enables table of contents
  toc_ordered: true # true uses ordered lists for TOC, false unordered
  toc_flatlist: false # true flattens the TOC into one level
  toc_min_level: 2 # minimum heading level to include in TOC, 3 hides ## Heading 2 and # Heading 1, 2 hides # Heading 1, 1 displays all headings, etc.
  toc_max_level: 6 # maximum heading level to include in TOC, 5 hides ###### Heading 6, 4 hides ##### Heading 5 and ###### Heading 6, etc.
  toc_collapsed: false # true starts the TOC collapsed when it is shown above the content
  toc_title: "Table of Contents" # heading of the TOC panel



Side panels and the page list

On viewports wide enough to fit it next to the content, the TOC is shown to the right of the content instead of above it. Whether it fits depends on content_max_width, forgejo_header and side_panel_width, so the theme works out the breakpoints from your configuration. When it doesn’t fit, the TOC stays above the content, where it can be collapsed.

The optional page list works the same way, in the left gutter, or above the TOC when there is no room. With both enabled, the TOC moves beside the content first, and the page list joins it on the left once there is room for both. It is built from your pages’ source paths: [00_Category/][00_Subcategory/]00_Page.md. Pages and folders are ordered by path, the numeric prefix is hidden, folders are collapsible, and folders containing the current page start open. A page’s title is used as its label, falling back to the cleaned-up file name.

# Default values
degit_theme:
  page_list: false # true enables the page list
  page_list_collapsed: false # true starts the page list collapsed when it is shown above the content
  page_list_title: "Pages" # heading of the page list panel
  page_list_exclude: [] # paths of pages to leave out, e.g. ["index.md"]
  side_panel_width: 240 # width in pixels of the panels beside the content

---
page_list: false # leaves this page out of the page list
---



flashbang

# Default values
degit_theme:
  flashbang: false # set to true to disappoint all of your ancestors

If you clicked on the link in the ToC or the anchor link… sorry about that. Click here to go back to dark mode.

If flashbang is enabled, the <html> element’s data-theme attribute is set to light. This can be toggled programmatically with JavaScript.

<!-- Resulting HTML -->
<!DOCTYPE html>
<html lang="en" data-theme="light">



Advanced

The déGit Pages Jekyll Theme exposes some extra options to customize the resulting website. The options are shared between the _config.yml site configuration, and individual pages’ front matter.

---
degit_theme:
  # Various config options go here
---
<!-- Rest of your content -->



Injecting CSS

degit_theme.styles can be used to inject custom CSS stylesheets into the page.

For site-wide styles, add them in your _config.yml:

degit_theme:
  styles:
    - /assets/mystyles.css # CSS from your source code
    - https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css # CSS from an external source

For page-specific styles, add them in the page’s front matter:

---
degit_theme:
  styles:
    - /assets/mystyles.css # CSS from your source code
    - https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css # CSS from an external source
---

Custom styles also support media queries.

degit_theme:
  styles:
    - /assets/mybasestyles.css # applied regardless of applicable media queries
    - href: /assets/myphonestyles.css # applied when the screen width is less than 600px
      media: "screen and (max-width: 600px)"

---
degit_theme:
  styles:
    - /assets/mybasestyles.css # applied regardless of applicable media queries
    - href: /assets/myphonestyles.css # applied when the screen width is less than 600px
      media: "screen and (max-width: 600px)"
---

Custom styles are injected into the <head> tag of the page.

    <!-- Resulting HTML -->
    <link rel="stylesheet" href="/assets/css/main.css">
    <link rel="icon" href="/favicon.ico">
    <link rel="stylesheet" href="/assets/mybasestyles.css"> <!-- your injected style -->
    <link rel="stylesheet" href="/assets/myphonestyles.css" media="screen and (max-width: 600px)"> <!-- your injected style -->



Injecting JavaScript

degit_theme.head_scripts and degit_theme.body_scripts can be used to inject custom JavaScript into the page. head_scripts get injected at the end of <head>, meanwhile body_scripts get injected at the end of <body>

For site-wide styles, add them in your _config.yml:

degit_theme:
  head_scripts:
    - https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js # Ideal for loading libraries and scripts that do not need the entire DOM rendered
  body_scripts:
    - /assets/myscript.js # Ideal for scripts that need the entire DOM rendered

For page-specific styles, add them in the page’s front matter:

---
degit_theme:
  head_scripts:
    - https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js # Ideal for loading libraries and scripts that do not need the entire DOM rendered
  body_scripts:
    - /assets/myscript.js # Ideal for scripts that need the entire DOM rendered
---

Custom scripts also support async, defer and type modifiers.

degit_theme:
  head_scripts:
    - /assets/somescript.js
    - src: /assets/someasyncscript.js
      async: true
  body_scripts:
    - src: /assets/somedeferredscript.js
      defer: true
    - src: /assets/somescriptwithcustomtype.js
      type: "module"

---
degit_theme:
  head_scripts:
    - /assets/somescript.js
    - src: /assets/someasyncscript.js
      async: true
  body_scripts:
    - src: /assets/somedeferredscript.js
      defer: true
    - src: /assets/somescriptwithcustomtype.js
      type: "module"
---