search

scottire / fastpages

Apache License 2.0
21 stars 8 forks source link

readme

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:

See below for a more detailed list of features.

See the demo site

Setup Instructions

  1. Generate a copy of this repo by clicking on this link. 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, plese 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.

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

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

Colab, Binder and GitHub Badges

This option works for notebooks only

Categories

# Set this to true to display tags on each post
show_tags: true

Enabling Comments

Blog posting is powered by Utterances, an open-source and ad-free way of implementing comments. All comments are stored in issues on your blog's GitHub repo. You can turn this on setting comments to true. This defaults to false.

To enable comments with Utterances you will need to do the following:

Setting an Image For Social Media

On social media sites like Twitter, an image preview can be automatically shown with your URL. Specifying the front matter image provides this metadata to social media sites to render this image for you. You can set this value as follows:

- image: images/diagram.png

Note: for this setting you can only reference image files and folders in the /images folder of your repo.

Hiding A Blog Post

You may want to prevent a blog post from being listed on the home page, but still have a public url that you can preview or share discreetly. You can hide a blog post from the home page by setting the front matter hide to true. This is set to false by default.

It is recommended that you use permalinks in order to generate a predictable url for hidden blog posts. You can also set the front matter search_exclude to false if you don't want users to find your hidden post in a search.

Pinning A Blog Post

By default, posts are sorted by date on your homepage. However, you may want one or more blog posts to always appear at the very top of your homepage. In other words, you may want certain posts to be "pinned" or "sticky". To accomplish this, specify the sticky_rank front matter in the order you would like your sticky posts to appear. Blog posts that do not set this parameter are sorted in the default way by date after the sticky posts.

For example, consider these three markdown posts (also works for notebooks).

2020-01-01-Post-One.md

---
title: Post One
sticky_rank: 1
---

2020-02-01-Post-Two.md

---
title: Post Two
sticky_rank: 2
---

2020-04-01-Post-Three.md

---
title: Post Three
---

However, since sticky_rank is specified, blog posts will first be sorted by sticky_rank in ascending order, then by date in descending order, so the order of these posts will appear like so:

_Without sticky_rank the above posts would actually be sorted in reverse order due to the dates associated with each post._

Note: pinning also works for notebooks:

# "My cool blog post"
> "Description of blog post"

- sticky_rank: 2

Toggle Search Visibility

fastpages comes with built in keyword search powered by lunr.js. You can prevent a blog post or page from appearing in search results by setting the front matter search_exclude to false. This is set to true by default.

Site Wide Configuration Options

It is recommended that everyone personalizes their blogging site by setting site-wide configration options. These options can be found in /_config.yml. Below is a description of various options that are available.

Adjusting Page Width

You can adjust the page width of fastpages on various devices by editing /_sass/minima/custom-variables.scss.

These are the default values, which can be adjusted to suit your preferences:

// width of the content area
// can be set as "px" or "%"
$content-width:    1000px;
$on-palm:          800px;
$on-laptop:        1000px;
$on-medium:        1000px;
$on-large:         1200px;

Syntax Highlighting

fastpages overrides the default syntax highlighting of minima with the Dracula theme.

Adding Citations via BibTeX

Users who prefer to use the citation system BibTeX may do so; it requires enabling the jekyll-scholar plugin. Please see Citations in Fastpages via BibTeX and jekyll-scholar for instructions on implementing this.

Writing Blog Posts With Jupyter

Hide Input/Output Cells

Place the comment #hide at the beginning of a code cell and it wil hide both the input and the output of that cell.

A #hide_input comment at the top of any cell will only hide the input.

Furthermore, the hide input Jupyter Extension can be used to hide cell inputs or outputs, which will be respected by fastpages.

Collapsable Code Cells

You may want some code to be hidden in a collapsed element that the user can expand, rather than completely hiding the code from the reader.

Embedded Twitter and YouTube Content

In a markdown cell in your notebook, use the following markdown shortcuts to embed Twitter cards and YouTube Videos.

  > youtube: https://youtu.be/your-link
  > twitter: https://twitter.com/some-link

Adding Footnotes

Adding footnotes in notebooks is a bit different than markdown. Please see the Detailed Guide To Footnotes in Notebooks.

Automatically Convert Notebooks To Blog Posts

  1. Save your notebook with the naming convention YYYY-MM-DD-*. into the /_notebooks or /_word folder of this repo, respectively. For example 2020-01-28-My-First-Post.ipynb. This naming convention is required by Jekyll to render your blog post.

    • Be careful to name your file correctly! It is easy to forget the last dash in YYYY-MM-DD-. Furthermore, the character immediately following the dash should only be an alphabetical letter. Examples of valid filenames are:

      2020-01-28-My-First-Post.ipynb
2012-09-12-how-to-write-a-blog.ipynb
      • If you fail to name your file correctly, fastpages will automatically attempt to fix the problem by prepending the last modified date of your file to your generated blog post, however, it is recommended that you name your files properly yourself for more transparency.

  2. Commit and push your file(s) to GitHub in your repository's master branch.

  3. GitHub will automatically convert your files to blog posts. It will take ~5 minutes for the conversion process to take place. You can click on the Actions tab of your repo to view the logs of this process. There will be two workflows that are triggered with each push you make to your master branch: (1) "CI" and (2) "GH Pages Status". Both workflows must complete with a green checkmark for your latest commit before your site is updated.

  4. If you wish, you can preview how your blog will look locally before commiting to GitHub. See this section for a detailed guide on running the preview locally.

Writing Blog Posts With Markdown

If you are writing your blog post in markdown, save your .md file into the /_posts folder with the same naming convention (YYYY-MM-DD-*.md) specified for notebooks.

Writing Blog Posts With Microsoft Word

Save your Microsoft Word documents into the /_word folder with the same naming convention (YYYY-MM-DD-*.docx) specified for notebooks.

Note: alt text in Word documents are not yet supported by fastpages, and will break links to images.

Specifying front-matter for Word documents

fastpages does not have a robust way to specify front matter for Word documents. At the moment, you can only specify front matter globally for all Word documents by editing _action_files/word_front_matter.txt.

To specify unique front matter per Word document, you will need to convert Word to markdown files manually. You can follow the steps in this blog post, which walk you through how to use pandoc to do the conversion. Note: If you wish to customize your Word generated blog post in markdown, make sure you delete your Word document from the _word directory so your markdown file doesn’t get overwritten!

_If your primary method of writing blog posts is Word documents, and you plan on always manually editing markdown files converted from Word, you are probably better off using fast_template instead of fastpages._

Running the blog on your local machine

See the development guide.

Using The GitHub Action & Your Own Custom Blog

The fastpages action allows you to convert notebooks from /_notebooks and word documents from /_word directories in your repo into Jekyll compliant blog post markdown files located in /_posts. Note: This directory structure is currently inflexible for this Action, as it is designed to be used with Jekyll.

If you already have sufficient familiarity with Jekyll and wish to use this automation in your own theme, you can use this GitHub Action by referencing fastai/fastpages@master as follows:

...

uses: fastai/fastpages@master

...

An illustrative example of what a complete workflow may look like:

jobs:
  build-site:
    runs-on: ubuntu-latest
    ...

    - name: convert notebooks and word docs to posts
      uses: fastai/fastpages@master

    ...

    - name: Jekyll build
      uses: docker://jekyll/jekyll
      with:
        args: jekyll build

    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.event_name == 'push'
      with:
        deploy_key: ${{ secrets.SSH_DEPLOY_KEY }}
        publish_branch: gh-pages
        publish_dir: ./_site

Note that this Action does not have any required inputs, and has no output variables.

Optional Inputs

See the API spec for this action in action.yml

Detailed instructions on how to customize this blog are beyond the scope of this README. ( We invite someone from the community to contribute a blog post on how to do this in this repo! )

Contributing To Fastpages

Please see the contributing guide.

Upgrading Fastpages

Please see the upgrading guide.

FAQ

    ...

    - name: convert notebooks and word docs to posts
      uses: fastai/fastpages@master
      with:
        BOOL_SAVE_MARKDOWN: true
        SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}

    ...

Customizing Fastpages

fastpages builds upon the minima theme. If you want to customize the styling or layout of fastpages, you can find instructions in minima's README. It is a good idea to read the full contents of the README to understand the directory structure. Furthermore, it is a good idea to have a basic understanding of Jekyll before customizing your theme. For those new to Jekyll, the official docs are a good place to start. Concretely, you can override css in fastpages in _sass/minima/custom-styles.scss. NOTE that minima's "skins" feature is currently incompatible with fastpages' css settings.

If you choose to make customizations to fastpages It is possible that customizations you make could collide with current or future versions of fastpages and we recommend doing so only if you feel sufficiently comfortable with HTML and CSS.

Troubleshooting fastpages

Please see the troubleshooting guide.