Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/klemenjak/blog
https://github.com/klemenjak/blog
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/klemenjak/blog
- Owner: klemenjak
- License: apache-2.0
- Created: 2020-02-28T10:03:28.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-04-12T00:32:43.000Z (over 1 year ago)
- Last Synced: 2024-10-12T15:26:38.596Z (3 months ago)
- Language: Jupyter Notebook
- Size: 355 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[//]: # (BADGES SECTION: change `fastai` with your GitHub username and `fastpages` with the name of your repo)
[](https://github.com/fastai/nbdev)
[](https://fastpages.fast.ai/)
[//]: # (END OF BADGES SECTION)
# Welcome To `fastpages`
> An easy to use blogging platform, with support for Jupyter notebooks, Word docs, and Markdown.
`fastpages` uses [GitHub Actions](https://github.com/features/actions) to simplify the process of 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/) and GitHub automatically.
- Write posts on your local machine and [preview them with live reload](#running-the-blog-on-your-local-machine).
- Create posts, including formatting and images, directly from Microsoft Word documents.
- Create and edit [Markdown](https://guides.github.com/features/mastering-markdown/) posts entirely online using GitHub's built-in markdown editor.
- Embed Twitter cards and YouTube videos.
- Categorization of blog posts by user-supplied tags for discoverability.
See below for a more detailed list of features.
**[See the demo site](https://fastpages.fast.ai/)**
---
- [Welcome To `fastpages`](#welcome-to-fastpages)
- [Setup Instructions](#setup-instructions)
- [Front-Matter related options](#front-matter-related-options)
- [Configure Title & Summary](#configure-title--summary)
- [Table of Contents](#table-of-contents)
- [Colab And GitHub Badges](#colab-and-github-badges)
- [Tags](#categories)
- [Enabling Comments](#enabling-comments)
- [Setting an Image For Social Media](#setting-an-image-for-social-media)
- [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)
- [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)
- [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)
- [FAQ](#faq)
## Setup Instructions
1. Generate a copy of this repo by clicking [on this link](https://github.com/fastai/fastpages/generate). 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.
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.
## Front-Matter related options
In a notebook, [front matter](https://jekyllrb.com/docs/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
- 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"
- summary: "Awesome summary"
- toc: false
- branch: master
- badges: true
- comments: true
- image: images/some_folder/your_image.png
- 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 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 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`
### 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:
` - 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
Blog posting 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.**
## 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. If you only want to hide just the input or the output, use the `hide input` [Jupyter Extension](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/hide_input/readme.html)
### Collapsable Code Cells
You may want to have code code be hidden from view under 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.
### 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
```
### 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.
# Running the blog on your local machine
See the [development guide](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](CONTRIBUTING.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.