: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

---

<!-- TOC depthFrom:1 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->

• 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
    • Embedded Twitter and YouTube Content
    • Adding Footnotes
    • Automatically Convert Notebooks To Blog Posts
  • Writing Blog Posts With Markdown
  • Writing Blog Posts With Microsoft Word
    • Specifying front-matter for Word documents
• Running the blog on your local machine
• Using The GitHub Action & Your Own Custom Blog
  • Optional Inputs
• Contributing To Fastpages
• Upgrading Fastpages
• FAQ
• Customizing Fastpages
• Troubleshooting fastpages

<!-- /TOC -->

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_