Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/fastai/fastpages

An easy to use blogging platform, with enhanced support for Jupyter Notebooks.
https://github.com/fastai/fastpages

actions data-science fastai github-pages jekyll jekyll-blog jupyter jupyter-lab jupyter-notebooks literate-programming nbdev python visualization visualization-tools

Last synced: 24 days ago
JSON representation

An easy to use blogging platform, with enhanced support for Jupyter Notebooks.

Lists

README 

        
[//]: # (BADGES SECTION: change `fastai` with your GitHub username and `fastpages` with the name of your repo)



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

![](https://github.com/fastai/fastpages/workflows/GH-Pages%20Status/badge.svg)

[![](https://img.shields.io/static/v1?label=fastai&message=nbdev&color=57aeac&labelColor=black&style=flat&logo=data:image/png;base64,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)](https://github.com/fastai/nbdev)

[![](https://img.shields.io/static/v1?label=View%20Demo%20Site&message=link&labelColor=2f363d&color=blue&style=flat&logo=github&logoColor=959da5)](https://fastpages.fast.ai/)



[//]: # (END OF BADGES SECTION)



# :warning: 



# This Project Is Deprecated.  We recommend using [Quarto](https://quarto.org/) instead.  See this [migration guide](https://nbdev.fast.ai/tutorials/blogging.html) if you are already using fastpages. 



More information on why we deprecated this project is [here](https://forums.fast.ai/t/fastpages-deprecating-fastpages-in-favor-of-quarto/99095).



# :warning:



# Welcome To `fastpages`



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



![](images/diagram.png)



`fastpages` uses [GitHub Actions](https://github.com/features/actions) to simplify the process of creating [Jekyll blog posts](https://jekyllrb.com/) on [GitHub Pages](https://pages.github.com/) 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](https://jupyter.org/); Notebook posts support features such as:

    - Interactive visualizations made with [Altair](https://altair-viz.github.io/) 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](https://colab.research.google.com/), [Deepnote](https://deepnote.com/) 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](https://guides.github.com/features/mastering-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](#running-the-blog-on-your-local-machine).



See below for a more detailed list of features.



**[See the demo site](https://fastpages.fast.ai/)**



---



- [Welcome To `fastpages`](#welcome-to-fastpages)

    - [`fastpages` provides the following features:](#fastpages-provides-the-following-features)

  - [Setup Instructions](#setup-instructions)

  - [Customizing Blog Posts With Front Matter](#customizing-blog-posts-with-front-matter)

    - [Configure Title & Summary](#configure-title--summary)

    - [Table of Contents](#table-of-contents)

    - [Colab, Binder, Deepnote and GitHub Badges](#colab-binder-deepnote-and-github-badges)

    - [Categories](#categories)

    - [Enabling Comments](#enabling-comments)

    - [Setting an Image For Social Media](#setting-an-image-for-social-media)

    - [Hiding A Blog Post](#hiding-a-blog-post)

    - [Pinning A Blog Post](#pinning-a-blog-post)

    - [Toggle Search Visibility](#toggle-search-visibility)

  - [Site Wide Configuration Options](#site-wide-configuration-options)

  - [Adjusting Page Width](#adjusting-page-width)

  - [Annotations and Highlighting With hypothes.is](#annotations-and-highlighting-with-hypothesis)

  - [Subscribing with RSS](#subscribing-with-rss)

  - [Syntax Highlighting](#syntax-highlighting)

  - [Dark Mode](#dark-mode)

  - [Adding Citations via BibTeX](#adding-citations-via-bibtex)

  - [Writing Blog Posts With Jupyter](#writing-blog-posts-with-jupyter)

    - [Hide Input/Output Cells](#hide-inputoutput-cells)

    - [Collapsable Code Cells](#collapsable-code-cells)

    - [Embedded Twitter and YouTube Content](#embedded-twitter-and-youtube-content)

    - [Adding Footnotes](#adding-footnotes)

    - [Automatically Convert Notebooks To Blog Posts](#automatically-convert-notebooks-to-blog-posts)

  - [Writing Blog Posts With Markdown](#writing-blog-posts-with-markdown)

  - [Writing Blog Posts With Microsoft Word](#writing-blog-posts-with-microsoft-word)

    - [Specifying front-matter for Word documents](#specifying-front-matter-for-word-documents)

- [Running the blog on your local machine](#running-the-blog-on-your-local-machine)

- [Using The GitHub Action & Your Own Custom Blog](#using-the-github-action--your-own-custom-blog)

    - [Optional Inputs](#optional-inputs)

- [Contributing To Fastpages](#contributing-to-fastpages)

- [Upgrading Fastpages](#upgrading-fastpages)

- [FAQ](#faq)

- [Customizing Fastpages](#customizing-fastpages)

- [Troubleshooting fastpages](#troubleshooting-fastpages)



## Setup Instructions



1.  Generate a copy of this repo by clicking [on this link](https://github.com/fastai/fastpages/generate). 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](https://youtu.be/L0boq3zqazI) 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`.  



![](2022-05-15-07-21-16.png)



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



![](2022-05-15-07-25-15.png)



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.



![](2022-05-15-07-24-25.png)



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](https://jekyllrb.com/docs/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:



  ```markdown

  # "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:



  ```yaml

  ---

  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](https://jekyllrb.com/docs/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](https://rollout.io/blog/yaml-tutorial-everything-you-need-get-started/) 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](https://guides.github.com/features/mastering-markdown/)!  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`.  This defaults to `true`

  - By default, when you omit this parameter from your front matter, or you set `badges: true`, **all four badges (GitHub, Binder, Deepnote, Colab)** will appear by default. You can adjust these defaults in with the `default_badges` parameter in [Site Wide Configuration Options](#site-wide-configuration-options).

    - If only want to hide a badge on an individual post, you can set the front matter `hide_{github,colab,binder,deepnote}_badge: true`.  For example, if you wanted to hide the Binder badge for an individual notebook but you want the other badges to show up, you can set this in your front matter:



      ```yaml

      - badges: true

      - hide_binder_badge: true

      ```

  - **Note about Binder**: Binder allows you to customize the dependencies and other aspects of the Jupyter Notebook environment for your readers. The easiest way is to add a `requirements.txt` file with common packages you use for all your notebooks at the root of your repository, you can learn more [on the official Binder docs](https://mybinder.readthedocs.io/en/latest/introduction.html).



### Categories

  - You can have a comma seperated list inside square brackets of categories for a blog post, which will make the post visible on the tags page of your blog's site.  For example:



    In a notebook:



    ```

    # "My Title"

    - categories: [fastpages, jupyter]

    ```



    In a markdown document:



    ```

    ---

    title: "My Title"

    categories: [fastpages, jupyter]

    ---

    ```



  You can see a preview of what this looks like [here](https://fastpages.fast.ai/categories/).



  - You can toggle the display of tags on/off by setting `show_tags` to `true` or `false` in `_config.yml`:



```yaml

# Set this to true to display tags on each post

show_tags: true

```



### Enabling Comments



Commenting on blog posts is powered by [Utterances](https://github.com/utterance/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](https://github.com/utterance/utterances) you will need to do the following:



  - Make sure the repo is public, otherwise your readers will not be able to view the issues/comments.

  - Make sure the [utterances app](https://github.com/apps/utterances) is installed on the repo, otherwise users will not be able to post comments.

  - If your repo is a fork, navigate to it's settings tab and confirm the issues feature is turned on.



### 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](https://jekyllrb.com/docs/permalinks/) in order to generate a predictable url for hidden blog posts.  You can also set the front matter `search_exclude` to `true` 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`

```yaml

---

title: Post One

sticky_rank: 1

---

```



`2020-02-01-Post-Two.md`

```yaml

---

title: Post Two

sticky_rank: 2

---

```



`2020-04-01-Post-Three.md`

```yaml

---

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:



- Post One

- Post Two

- Post Three



_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](https://lunrjs.com/).  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.



- `title`: this is the title that appears on the upper left hand corner on the header of all your pages.  

- `description`: this description will show up in various places when a preview for your site is generated (for example, on social media).

- `github_username`: this allows your site to display a link to your GitHub page in the footer.

- `github_repo`: this allows your site to render links back to your repository for various features such as links to GitHub, Colab and Deepnote for notebooks.

- `url`: This does not need to be changed unless you have a custom domain.  **Note: leave out the trailing / from this value.**

- `baseurl`: See the comments in `/_config.yml` for instructions ( "Special Instructions for baseurl" on setting this value properly.  If you do not have a custom domain, then you can likely ignore this option.

- `email`: this is currently unused.  Ignore.

- `twitter_username`: creates a link in your footer to your twitter page.

- `use_math`: Set this to `true` to get LaTeX math equation support.  This is off by default as it otherwhise loads javascript into each page that may not be used.

- `show_description`: This shows a description under the title of your blog posts on your homepage that contains a list of your blog posts.  Set to `true` by default.

- `google_analytics`: Optionally use a [Google Analytics](http://www.google.com/analytics/) ID for tracking if desired.

- `show_image`: If set to true, this uses the `image` parameter in the front matter of your blog posts to render a preview of your blogs as shown below.  This is set to `false` by default.

  When show_image is set to `true` your homepage will look like this:



  ![home page](/_fastpages_docs/_show_image_true.png)



- `show_tags`: You can toggle the display of tags on your blog posts on or off by setting this value to `false`.  This is set to `true` by default, which which renders the following links for tags on your blog posts like this:



  ![tags](_fastpages_docs/_post_tags.png)



- `pagination`: This is the maximum number of posts to show on each page of your home page.  Any posts exceeding this amount will be paginated onto another page.  This is set to `15` by default.  When this is triggered, you will see pagination at the bottom of your home page appear like this:



  ![paginate](_fastpages_docs/_paginate.png)



  Note: if you are using an older version of fastpages, **you cannot use the automated upgrade process** to get pagination.  Instead you must follow these steps:



    1. Rename your index.md file to index.html

         > mv index.md index.html

    2. Replace the `Gemfile` and `Gemfile.lock` in the root of your repo with the files in this repo.

    3. Edit your `_config.yml` as follows (look at [_config.yml](_config.yml) for an example):

        ```yaml

        gems:

        - jekyll-paginate



        paginate: 10

        paginate_path: /page:num/

        ```



    _Alternatively, you can copy all of your posts over to a newly created  repository created from the fastpages template._



- `default_badges`: By default GitHub, Binder, Deepnote, and Colab badges will show up on notebook blog posts. You can adjust these defaults by setting the appropriate value in `default_badges` to false.  For example, if you wanted to turn Binder badges off by default, you would change `default_badges` to this:



  ```yaml

  default_badges:

    github: true

    binder: false

    deepnote: false

    colab: true

  ```



- `html_escape`: this allows you to toggle escaping of HTML in various components of blog posts on or off.  At this moment, you can only toggle this for the `description` field in your posts.  

This is set to `false` by default.



## Adjusting Page Width



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



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



```scss

// 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;

```



## Annotations and Highlighting With hypothes.is



[hypothes.is](https://web.hypothes.is/) is an open platform that provides a way to annotate and higlight pages, which can be either public or private.  When this feature is enabled, readers of your blog will be presented with the following tooltip when highlighting text:



![annotation](_fastpages_docs/annotate.png)



**This is disabled by default in fastpages.** You can enable or disable this in your [_config.yml](_config.yml) file by setting `annotations` to `true` or `false`:



```yaml

# Set this to true to turn on annotations with hypothes.is

annotations: false

```



> You can customize hypothes.is by reading [these configuration options](http://h.readthedocs.io/projects/client/en/latest/publishers/config/).  It is also a good idea to read [these docs](https://web.hypothes.is/for-publishers/#embedding) if you want to do more with hypothes.is.  However, before trying to customize this feature you should read the [customizing fastpages](#customizing-fastpages) section for important caveats.



## Subscribing with RSS



You can direct your readers to subscribe with [RSS feeds](https://en.wikipedia.org/wiki/RSS).  There are many RSS subscription services available on the internet.  Some examples include:



1. [Feedrabbit](https://feedrabbit.com/)

2. [Blogtrottr](https://blogtrottr.com/)



## Syntax Highlighting



`fastpages` overrides the default syntax highlighting of minima with the [Dracula theme](https://draculatheme.com/).  



- The default highlighting in fastpages looks like this:



  ![default-highlighting](_fastpages_docs/highlight_dracula.png)



- However, you can make the syntax highlighting to look like this, if you choose:



  ![default-highlighting](_fastpages_docs/highlight_original.png)



  If you wish to revert to the light theme above, you can remove the below line in [_sass/minima/custom-styles.scss](_sass/minima/custom-styles.scss)



  ```scss

  @import "minima/fastpages-dracula-highlight";

  ```

- If you don't like either of these themes, you can add your own CSS in [`_sass/minima/custom-styles.scss`](_sass/minima/custom-styles.scss).  See [customizing fastpages](#customizing-fastpages) for more details.



## Dark Mode



[This blog post](https://prudhvirampey.com/blog/colours/jekyll/css/fastpages/2020/10/30/hello-dark-mode.html) describes how to enable Dark Mode for fastpages.



## Adding Citations via BibTeX



Users who prefer to use the citation system BibTeX may do so; it requires enabling the [jekyll-scholar](https://github.com/inukshuk/jekyll-scholar) plugin. Please see [Citations in Fastpages via BibTeX and jekyll-scholar](https://drscotthawley.github.io/devblog4/2020/07/01/Citations-Via-Bibtex.html) 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](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/hide_input/readme.html) 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.



- To include code in a collapsable cell that **is collapsed by default**, place the comment `#collapse` at the top of the code cell.

- To include code in a collapsable cell that **is open by default**, place the comment `#collapse_show` or `#collapse-show` at the top of the code cell.

- To include the output under a collapsable element that is closed by default, place the comment `#collapse_output` or `#collapse-output` at the top of the code cell.



### Embedded Twitter and YouTube Content

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



  ```markdown

  > 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](https://github.com/fastai/fastpages/blob/master/_fastpages_docs/NOTEBOOK_FOOTNOTES.md).



### 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](https://jekyllrb.com/docs/posts/) 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:



        ```shell

        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](https://help.github.com/en/github/managing-files-in-a-repository/adding-a-file-to-a-repository-using-the-command-line) 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](#running-the-blog-on-your-local-machine) 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](https://support.office.com/en-us/article/add-alternative-text-to-a-shape-picture-chart-smartart-graphic-or-other-object-44989b2a-903c-4d9a-b742-6a75b451c669) 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](https://jekyllrb.com/docs/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](_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](https://www.fast.ai/2020/01/18/gitblog/), which walk you through how to use [pandoc](https://pandoc.org/installing.html) 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](https://github.com/fastai/fast_template) instead of fastpages._



# Running the blog on your local machine



See the [development guide](_fastpages_docs/DEVELOPMENT.md).



# 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](https://jekyllrb.com/) 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](https://jekyllrb.com/) and wish to use this automation in your own theme,  you can use this GitHub Action by referencing `fastai/fastpages@master` as follows:



```yaml

...



uses: fastai/fastpages@master



...

```

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



```yaml

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



  - `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](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](_fastpages_docs/CONTRIBUTING.md).



# Upgrading Fastpages



Please see the [upgrading guide](_fastpages_docs/UPGRADE.md).



# FAQ



- **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:



```yaml

    ...



    - name: convert notebooks and word docs to posts

      uses: fastai/fastpages@master

      with:

        BOOL_SAVE_MARKDOWN: true

        SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}



    ...

```



- **Q:** Can I use `fastpages` for Jekyll docs sites or for things that are not Jekyll blog posts?  **A:** At the moment, `fastpages` is a highly opinionated solution that works only for Jekyll blog posts.  If you want to write documentation for your module or library with Jupyter notebooks, we suggest you use [fastai/nbdev](https://github.com/fastai/nbdev) which is expressly built for this purpose.



- **Q:** What is the difference between [fast_template](https://github.com/fastai/fast_template) and fastpages?  Which one should I use?  **A:** Because `fastpages` is more flexible and extensible, we recommend using it where possible. `fast_template` may be a better option for getting folks blogging who have no technical expertise at all, and will only be creating posts using Github's integrated online editor.



# Customizing Fastpages



fastpages builds upon the [minima theme](https://github.com/jekyll/minima).  If you want to customize the styling or layout of fastpages, you can find instructions [in minima's README](https://github.com/jekyll/minima/blob/master/README.md).  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](https://jekyllrb.com/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](https://github.com/fastai/fastpages/blob/master/_fastpages_docs/TROUBLESHOOTING.md).