:warning:

This Project Is Deprecated. We recommend using Quarto instead. See this migration guide if you are already using fastpages.

More information on why we deprecated this project is here.

:warning:

Welcome To fastpages

An easy to use blogging platform, with support for Jupyter notebooks, Word docs, and Markdown.

fastpages uses GitHub Actions to simplify the process of creating Jekyll blog posts on GitHub Pages from a variety of input formats.

fastpages provides the following features:

• Create posts containing code, outputs of code (which can be interactive), formatted text, etc directly from Jupyter Notebooks; Notebook posts support features such as:
  • Interactive visualizations made with Altair remain interactive.
  • Hide or show cell input and output.
  • Collapsable code cells that are either open or closed by default.
  • Define the Title, Summary and other metadata via a special markdown cells
  • Ability to add links to Colab, Deepnote and GitHub automatically.
• Support for comments, supported natively through GitHub Issues.
• Built-in search.
• Support for customizing the styling of your site.
• Embed Twitter cards and YouTube videos.
• Categorization of blog posts by user-supplied tags for discoverability.
• Create and edit Markdown posts.
• Create posts, including formatting and images, directly from Microsoft Word documents.
• Write posts on your local machine and preview them with live reload.

See below for a more detailed list of features.

See the demo site

---

• Welcome To fastpages
  • fastpages provides the following features:
  • Setup Instructions
  • Customizing Blog Posts With Front Matter
    • Configure Title & Summary
    • Table of Contents
    • Colab, Binder, Deepnote and GitHub Badges
    • Categories
    • Enabling Comments
    • Setting an Image For Social Media
    • Hiding A Blog Post
    • Pinning A Blog Post
    • Toggle Search Visibility
  • Site Wide Configuration Options
  • Adjusting Page Width
  • Annotations and Highlighting With hypothes.is
  • Subscribing with RSS
  • Syntax Highlighting
  • Dark Mode
  • Adding Citations via BibTeX
  • Writing Blog Posts With Jupyter
    • Hide Input/Output Cells
    • Collapsable Code Cells

Setup Instructions

1. Generate a copy of this repo by clicking on this link. Make sure to sign in to your account, or you will see a 404 error. Name your repo anything you like except {your-username}.github.io.

2. GitHub Actions will automatically open a PR on your new repository ~ 30 seconds after the copy is created. Follow the instructions in that PR to continue.

If you are not seeing a PR, please make sure you have third party actions enabled in your organization: Settings -> Actions -> Actions Permissions -> Enable local and third party Actions for this repository

For a live walk-through of the setup steps (with some additional tips) see this video tutorial of setting up a fastpages blog by Abdul Majed.

3. In some cases because of permissions step 2 may fail to create a Pull Request. If this occurs, go to your repository settings and in the Actions section, grant Read and Write permissions and check Allow GitHub Actions to create and approve pull requests.

Once you have granted permissions, go to the Actions tab at the top of your repository home page, where you will be presented with a list of Actions runs. First click on the failed run (the item with the red X):

You will be taken to a screen where there will be a button on the upper right hand side allowing you to re-run jobs.

After doing this, a pull request should appear.

4. To create your first post, add content in the _posts, _notebooks or _word directories. You can follow examples of content in those folders in this repo of how to structure the content. The most important thing to pay attention to is the front matter, which is discussed in more detail below. Furthermore, you can add additional pages that will appear on your blog's navbar in the _pages directory. Note that content in the _word directory does not support front matter.

Customizing Blog Posts With Front Matter

Front matter allows you to toggle various options on/off for each blog post, as well as pass metadata to various features of fastpages.

In a notebook, front matter is defined as a markdown cell at the beginning of the notebook with the following contents:

# "Title"
> "Awesome summary"

- toc: false
- branch: master
- badges: true
- comments: true
- categories: [fastpages, jupyter]
- image: images/some_folder/your_image.png
- hide: false
- search_exclude: true
- metadata_key1: metadata_value1
- metadata_key2: metadata_value2

Similarly, in a markdown document the same front matter would be defined like this at the beginning of the document:

---
title: "My Title"
description: "Awesome description"
layout: post
toc: false
comments: true
image: images/some_folder/your_image.png
hide: false
search_exclude: true
categories: [fastpages, jupyter]
metadata_key1: metadata_value1
metadata_key2: metadata_value2
---

Additional metadata is optional and allows you to set custom front matter.

Note that anything defined in front matter must be valid YAML. Failure to provide valid YAML could result in your page not rendering in your blog. For example, if you want a colon in your title you must escape it with double quotes like this:

- title: "Deep learning: A tutorial"

See this tutorial on YAML for more information.

Configure Title & Summary

• Replace Title, with your desired title, and Awesome summary with your desired summary.

Note: It is recommended to enclose these values in double quotes, so that you can escape colons and other characters that may break the YAML parser.

Table of Contents

• fast_template will automatically generate a table of contents for you based on markdown headers! You can toggle this feature on or off by setting toc: to either true or false.

Colab, Binder, Deepnote and GitHub Badges

This option works for notebooks only

• The branch field is used to optionally render a link your notebook to Colab and GitHub in your blog post. It'll default to master if you don't specify it in the notebook.
• If you do not want to show Colab / GitHub badges on your blog post (perhaps because your repo is private and the links would be broken) set badges to false. T