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

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

• Interactive visualizations made with Altair remain interactive.

• Ability to hide cells by placing the comment #hide at the top of any cell. (To hide only the input to a cell use the hide input Jupyter extension).

• Add jekyll warnings, important or note banners with appropriate block quotes by using special markdown syntax defined here.

• Ability to embed twitter cards and youtube videos via the following markdown syntax:

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

• Define the Title, Summary and other metadata for your blog post via a special markdown cell at the beginning of your notebook as follows:

  # Title
  > Awesome summary
  - toc: False
  - metadata_key1: metadata_value1
  - metadata_key2: metadata_value2

• Notebooks are exported to HTML in a lightweight manner to allow you to customize CSS and styling. CSS can optionally be modified in /assets/main.scss.

• The notebook to blog conversion is powered by nbdev, which is under active development. Check the nbdev docs, particularly the export2html section, for a complete list of features that may be useful for notebooks.

See the demo site

1. Fork this repo

2. Change the badges on this README to point to your repository instead of this one. For example, instead of

   ![](https://github.com/fastai/fastpages/workflows/CI/badge.svg)

   this would be

   ![](https://github.com/your-username/your-repo-name/workflows/CI/badge.svg)

3. Change baseurl: in _config.yaml to the name of your repository. For example, instead of

   baseurl: "/fastpages"

   this would be

   baseurl: "/your-repo-name"

4. Follow these instructions to create an ssh-deploy key. Make sure you select Allow write access when adding this key to your GitHub account.

5. Follow these instructions to upload your deploy key as an encrypted secret on GitHub. Make sure you name your key SSH_DEPLOY_KEY.

1. Create a Jupyter Notebook or Word Document with the content of your blog post.

2. For Jupyter notebooks, create a markdown cell at the beginning of the notebook with the following contents:

   # Title
   > Awesome summary
   - toc: False
   - metadata_key1: metadata_value1
   - metadata_key2: metadata_value2

   • Replace Title, with your desired title, and Awesome summary with your desired summary.
   • 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.
   • Additional metadata is optional and allows you to set custom front matter.

3. Save your notebook or word document 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.docx

   • 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.

4. If you are writing your blog post in markdown, save your .md file into the /_posts folder with the same file naming convention as mentioned above.

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

6. GitHub will automatically convert your files to blog posts. You can click on the Actions tab of your repo to view the logs of this process.

The fastpages action allows you to convert notebooks from /_notebooks and word documents from /_word directories into your rep 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@v2
      if: github.event_name == 'push'
      env:
        ACTIONS_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.

• BOOL_SAVE_MARKDOWN: Either 'true' or 'false'. Whether or not to commit converted markdown files from notebooks and word documents into the _posts directory in your repo. This is useful for debugging. default: false
• SSH_DEPLOY_KEY: a ssh deploy key is required if BOOL_SAVE_MARKDOWN = 'true'

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! )

Please see the development guide.

• Q: Where are the markdown files in _posts/ that are generated from my Jupyter notebooks or word documents? A: The GitHub Actions workflow in this repo converts your notebook and word documents to markdown on the fly before building your site, but never commits these intermediate markdown files to this repo. This is in order to save you from the annoyance of your local environment being constantly out of sync with your repository. You can optionally see these intermediate markdown files by setting the BOOL_SAVE_MARKDOWN and SSH_DEPLOY_KEY inputs to the fastpages action in your .github/workflows/ci.yaml file as follows:

    ...

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

    ...