_notebooks/2020-02-21-introducing-fastpages.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introducing fastpages\n",
    "> An easy to use blogging platform with extra features for Jupyter Notebooks.\n",
    "\n",
    "- toc: true \n",
    "- badges: true\n",
    "- comments: true\n",
    "- author: Jeremy Howard & Hamel Husain\n",
    "- image: images/diagram.png\n",
    "- categories: [fastpages, jupyter]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![](https://github.com/fastai/fastpages/raw/master/images/diagram.png \"https://github.com/fastai/fastpages\")\n",
    "\n",
    "We are very pleased to announce the immediate availability of [fastpages](https://github.com/fastai/fastpages). `fastpages` is a platform which allows you to create and host a blog for free, with no ads and many useful features, such as:\n",
    "\n",
    "- Create posts containing code, outputs of code (which can be interactive), formatted text, etc directly from [Jupyter Notebooks](https://jupyter.org/); for instance see this great [example post](https://drscotthawley.github.io/devblog3/2019/02/08/My-1st-NN-Part-3-Multi-Layer-and-Backprop.html) from Scott Hawley.  Notebook posts support features such as:\n",
    "    - Interactive visualizations made with [Altair](https://altair-viz.github.io/) remain interactive.\n",
    "    - Hide or show cell input and output.\n",
    "    - Collapsable code cells that are either open or closed by default.\n",
    "    - Define the Title, Summary and other metadata via a special markdown cells\n",
    "    - Ability to add links to [Colab](https://colab.research.google.com/) and GitHub automatically.\n",
    "- Create posts, including formatting and images, directly from Microsoft Word documents.\n",
    "- Create and edit [Markdown](https://guides.github.com/features/mastering-markdown/) posts entirely online using GitHub's built-in markdown editor.\n",
    "- Embed Twitter cards and YouTube videos.\n",
    "- Categorization of blog posts by user-supplied tags for discoverability.\n",
    "- ... and [much more](https://github.com/fastai/fastpages)\n",
    "\n",
    "[fastpages](https://github.com/fastai/fastpages) relies on Github pages for hosting, and [Github Actions](https://github.com/features/actions) to automate the creation of your blog. The setup takes around three minutes, and does not require any technical knowledge or expertise. Due to built-in automation of fastpages, you don't have to fuss with conversion scripts.  All you have to do is save your Jupyter notebook, Word document or markdown file into a specified directory and the rest happens automatically. Infact, this blog post is written in a Jupyter notebook, which you can see with the \"View on GitHub\" link above.\n",
    "\n",
    "[fast.ai](https://www.fast.ai/) have previously released a similar project called [fast_template](https://www.fast.ai/2020/01/16/fast_template/), which is even easier to set up, but does not support automatic creation of posts from Microsoft Word or Jupyter notebooks, including many of the features outlined above.\n",
    "\n",
    "**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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setting Up Fastpages\n",
    "\n",
    "[The setup process](https://github.com/fastai/fastpages#setup-instructions) of fastpages is automated with GitHub Actions, too!  Upon creating a repo from the fastpages template, a pull request will automatically be opened (after ~ 30 seconds) configuring your blog so it can start working.  The automated pull request will greet you with instructions like this:\n",
    "\n",
    "![Imgur](https://i.imgur.com/JhkIip8.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All you have to do is follow these instructions (in the  PR you receive) and your new blogging site will be up and running!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Jupyter Notebooks & Fastpages\n",
    "\n",
    "In this post, we will cover special features that fastpages provides has for Jupyter notebooks.  You can also write your blog posts with Word documents or markdown in fastpages, which contain many, but not all the same features. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Options via FrontMatter\n",
    "\n",
    "The first cell in your Jupyter Notebook or markdown blog post contains front matter.  Front matter is metadata that can turn on/off options in your Notebook.  It is formatted like this:\n",
    "\n",
    "```\n",
    "# Title\n",
    "> Awesome summary\n",
    "- toc: true\n",
    "- branch: master\n",
    "- badges: true\n",
    "- comments: true\n",
    "- author: Hamel Husain & Jeremy Howard\n",
    "- categories: [fastpages, jupyter]\n",
    "```\n",
    "\n",
    "**All of the above settings are enabled in this post, so you can see what they look like!**\n",
    "\n",
    "- the summary field (preceeded by `>`) will be displayed under your title, and will also be used by social media to display as the description of your page.\n",
    "- `toc`: setting this to `true` will automatically generate a table of contents\n",
    "- `badges`: setting this to `true` will display Google Colab and GitHub links on your blog post.\n",
    "- `comments`: setting this to `true` will enable comments.  See [these instructions](https://github.com/fastai/fastpages#enabling-comments) for more details.\n",
    "- `author` this will display the authors names. \n",
    "- `categories` will allow your post to be categorized on a \"Tags\" page, where readers can browse your post by categories.\n",
    "\n",
    "\n",
    "_Markdown front matter is formatted similarly to notebooks.  The differences between the two can be [viewed on the fastpages README](https://github.com/fastai/fastpages#front-matter-related-options)._"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Code Folding"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "put a `#collapse_show` flag at the top of any cell if you want to **show** that cell by default, but give the reader the option to hide it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "#collapse\n",
    "import pandas as pd\n",
    "import altair as alt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "put a `#collapse_show` flag at the top of any cell if you want to **show** that cell by default, but give the reader the option to hide it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "#collapse_show\n",
    "cars = 'https://vega.github.io/vega-datasets/data/cars.json'\n",
    "movies = 'https://vega.github.io/vega-datasets/data/movies.json'\n",
    "sp500 = 'https://vega.github.io/vega-datasets/data/sp500.csv'\n",
    "stocks = 'https://vega.github.io/vega-datasets/data/stocks.csv'\n",
    "flights = 'https://vega.github.io/vega-datasets/data/flights-5k.json'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to completely hide cells (not just collapse them), [read these instructions](https://github.com/fastai/fastpages#hide-inputoutput-cells)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# hide\n",
    "df = pd.read_json(movies) # load movies data\n",
    "genres = df['Major_Genre'].unique() # get unique field values\n",
    "genres = list(filter(lambda d: d is not None, genres)) # filter out None values\n",
    "genres.sort() # sort alphabetically"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interactive Charts With Altair\n",
    "\n",
    "Interactive visualizations made with [Altair](https://altair-viz.github.io/) remain interactive!  \n",
    "\n",
    "We leave this below cell unhidden so you can enjoy a preview of syntax highlighting in fastpages, which uses the [Dracula theme](https://draculatheme.com/)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<div id=\"altair-viz-f9891c10f7fa4bcd80a749e3e62e065a\"></div>\n",
       "<script type=\"text/javascript\">\n",
       "  (function(spec, embedOpt){\n",
       "    const outputDiv = document.getElementById(\"altair-viz-f9891c10f7fa4bcd80a749e3e62e065a\");\n",
       "    const paths = {\n",
       "      \"vega\": \"https://cdn.jsdelivr.net/npm//vega@5?noext\",\n",
       "      \"vega-lib\": \"https://cdn.jsdelivr.net/npm//vega-lib?noext\",\n",
       "      \"vega-lite\": \"https://cdn.jsdelivr.net/npm//vega-lite@4.0.2?noext\",\n",
       "      \"vega-embed\": \"https://cdn.jsdelivr.net/npm//vega-embed@6?noext\",\n",
       "    };\n",
       "\n",
       "    function loadScript(lib) {\n",
       "      return new Promise(function(resolve, reject) {\n",
       "        var s = document.createElement('script');\n",
       "        s.src = paths[lib];\n",
       "        s.async = true;\n",
       "        s.onload = () => resolve(paths[lib]);\n",
       "        s.onerror = () => reject(`Error loading script: ${paths[lib]}`);\n",
       "        document.getElementsByTagName(\"head\")[0].appendChild(s);\n",
       "      });\n",
       "    }\n",
       "\n",
       "    function showError(err) {\n",
       "      outputDiv.innerHTML = `<div class=\"error\" style=\"color:red;\">${err}</div>`;\n",
       "      throw err;\n",
       "    }\n",
       "\n",
       "    function displayChart(vegaEmbed) {\n",
       "      vegaEmbed(outputDiv, spec, embedOpt)\n",
       "        .catch(err => showError(`Javascript Error: ${err.message}<br>This usually means there's a typo in your chart specification. See the javascript console for the full traceback.`));\n",
       "    }\n",
       "\n",
       "    if(typeof define === \"function\" && define.amd) {\n",
       "      requirejs.config({paths});\n",
       "      require([\"vega-embed\"], displayChart, err => showError(`Error loading script: ${err.message}`));\n",
       "    } else if (typeof vegaEmbed === \"function\") {\n",
       "      displayChart(vegaEmbed);\n",
       "    } else {\n",
       "      loadScript(\"vega\")\n",
       "        .then(() => loadScript(\"vega-lite\"))\n",
       "        .then(() => loadScript(\"vega-embed\"))\n",
       "        .catch(showError)\n",
       "        .then(() => displayChart(vegaEmbed));\n",
       "    }\n",
       "  })({\"config\": {\"view\": {\"continuousWidth\": 400, \"continuousHeight\": 300}}, \"layer\": [{\"mark\": \"line\", \"encoding\": {\"color\": {\"type\": \"nominal\", \"field\": \"symbol\"}, \"x\": {\"type\": \"temporal\", \"field\": \"date\"}, \"y\": {\"type\": \"quantitative\", \"field\": \"price\", \"scale\": {\"type\": \"log\"}}}}, {\"mark\": {\"type\": \"rule\", \"color\": \"#aaa\"}, \"encoding\": {\"x\": {\"type\": \"temporal\", \"field\": \"date\"}}, \"transform\": [{\"filter\": {\"selection\": \"selector002\"}}]}, {\"mark\": \"circle\", \"encoding\": {\"color\": {\"type\": \"nominal\", \"field\": \"symbol\"}, \"opacity\": {\"condition\": {\"value\": 1, \"selection\": \"selector002\"}, \"value\": 0}, \"x\": {\"type\": \"temporal\", \"field\": \"date\"}, \"y\": {\"type\": \"quantitative\", \"field\": \"price\", \"scale\": {\"type\": \"log\"}}}, \"selection\": {\"selector002\": {\"type\": \"single\", \"encodings\": [\"x\"], \"on\": \"mouseover\", \"nearest\": true, \"empty\": \"none\"}}}, {\"mark\": {\"type\": \"text\", \"align\": \"left\", \"dx\": 5, \"dy\": -5, \"stroke\": \"white\", \"strokeWidth\": 2}, \"encoding\": {\"color\": {\"type\": \"nominal\", \"field\": \"symbol\"}, \"text\": {\"type\": \"quantitative\", \"field\": \"price\"}, \"x\": {\"type\": \"temporal\", \"field\": \"date\"}, \"y\": {\"type\": \"quantitative\", \"field\": \"price\", \"scale\": {\"type\": \"log\"}}}, \"transform\": [{\"filter\": {\"selection\": \"selector002\"}}]}, {\"mark\": {\"type\": \"text\", \"align\": \"left\", \"dx\": 5, \"dy\": -5}, \"encoding\": {\"color\": {\"type\": \"nominal\", \"field\": \"symbol\"}, \"text\": {\"type\": \"quantitative\", \"field\": \"price\"}, \"x\": {\"type\": \"temporal\", \"field\": \"date\"}, \"y\": {\"type\": \"quantitative\", \"field\": \"price\", \"scale\": {\"type\": \"log\"}}}, \"transform\": [{\"filter\": {\"selection\": \"selector002\"}}]}], \"data\": {\"url\": \"https://vega.github.io/vega-datasets/data/stocks.csv\"}, \"height\": 400, \"width\": 700, \"$schema\": \"https://vega.github.io/schema/vega-lite/v4.0.2.json\"}, {\"mode\": \"vega-lite\"});\n",
       "</script>"
      ],
      "text/plain": [
       "alt.LayerChart(...)"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# select a point for which to provide details-on-demand\n",
    "label = alt.selection_single(\n",
    "    encodings=['x'], # limit selection to x-axis value\n",
    "    on='mouseover',  # select on mouseover events\n",
    "    nearest=True,    # select data point nearest the cursor\n",
    "    empty='none'     # empty selection includes no data points\n",
    ")\n",
    "\n",
    "# define our base line chart of stock prices\n",
    "base = alt.Chart().mark_line().encode(\n",
    "    alt.X('date:T'),\n",
    "    alt.Y('price:Q', scale=alt.Scale(type='log')),\n",
    "    alt.Color('symbol:N')\n",
    ")\n",
    "\n",
    "alt.layer(\n",
    "    base, # base line chart\n",
    "    \n",
    "    # add a rule mark to serve as a guide line\n",
    "    alt.Chart().mark_rule(color='#aaa').encode(\n",
    "        x='date:T'\n",
    "    ).transform_filter(label),\n",
    "    \n",
    "    # add circle marks for selected time points, hide unselected points\n",
    "    base.mark_circle().encode(\n",
    "        opacity=alt.condition(label, alt.value(1), alt.value(0))\n",
    "    ).add_selection(label),\n",
    "\n",
    "    # add white stroked text to provide a legible background for labels\n",
    "    base.mark_text(align='left', dx=5, dy=-5, stroke='white', strokeWidth=2).encode(\n",
    "        text='price:Q'\n",
    "    ).transform_filter(label),\n",
    "\n",
    "    # add text labels for stock prices\n",
    "    base.mark_text(align='left', dx=5, dy=-5).encode(\n",
    "        text='price:Q'\n",
    "    ).transform_filter(label),\n",
    "    \n",
    "    data=stocks\n",
    ").properties(\n",
    "    width=700,\n",
    "    height=400\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data Tables\n",
    "\n",
    "You can display tables per the usual way in your blog:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Title</th>\n",
       "      <th>Worldwide_Gross</th>\n",
       "      <th>Production_Budget</th>\n",
       "      <th>IMDB_Rating</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>The Land Girls</td>\n",
       "      <td>146083.0</td>\n",
       "      <td>8000000.0</td>\n",
       "      <td>6.1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>First Love, Last Rites</td>\n",
       "      <td>10876.0</td>\n",
       "      <td>300000.0</td>\n",
       "      <td>6.9</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>I Married a Strange Person</td>\n",
       "      <td>203134.0</td>\n",
       "      <td>250000.0</td>\n",
       "      <td>6.8</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Let's Talk About Sex</td>\n",
       "      <td>373615.0</td>\n",
       "      <td>300000.0</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Slam</td>\n",
       "      <td>1087521.0</td>\n",
       "      <td>1000000.0</td>\n",
       "      <td>3.4</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                        Title  Worldwide_Gross  Production_Budget  IMDB_Rating\n",
       "0              The Land Girls         146083.0          8000000.0          6.1\n",
       "1      First Love, Last Rites          10876.0           300000.0          6.9\n",
       "2  I Married a Strange Person         203134.0           250000.0          6.8\n",
       "3        Let's Talk About Sex         373615.0           300000.0          NaN\n",
       "4                        Slam        1087521.0          1000000.0          3.4"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "movies = 'https://vega.github.io/vega-datasets/data/movies.json'\n",
    "df = pd.read_json(movies)\n",
    "# display table with pandas\n",
    "df[['Title', 'Worldwide_Gross', \n",
    "    'Production_Budget', 'IMDB_Rating']].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Images w/Captions\n",
    "\n",
    "You can include markdown images with captions like this:\n",
    "\n",
    "```\n",
    "![](https://www.fast.ai/images/fastai_paper/show_batch.png \"Credit: https://www.fast.ai/2020/02/13/fastai-A-Layered-API-for-Deep-Learning/\")\n",
    "```\n",
    "\n",
    "\n",
    "![](https://www.fast.ai/images/fastai_paper/show_batch.png \"Credit: https://www.fast.ai/2020/02/13/fastai-A-Layered-API-for-Deep-Learning/\")\n",
    "\n",
    "Of course, the caption is optional."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tweetcards\n",
    "\n",
    "Typing `> twitter: https://twitter.com/jakevdp/status/1204765621767901185?s=20` will render this:\n",
    "\n",
    "> twitter: https://twitter.com/jakevdp/status/1204765621767901185?s=20"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Youtube Videos\n",
    "\n",
    "Typing `> youtube: https://youtu.be/XfoYk_Z5AkI` will render this:\n",
    "\n",
    "\n",
    "> youtube: https://youtu.be/XfoYk_Z5AkI"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Boxes / Callouts \n",
    "\n",
    "Typing `> Warning: There will be no second warning!` will render this:\n",
    "\n",
    "\n",
    "> Warning: There will be no second warning!\n",
    "\n",
    "\n",
    "\n",
    "Typing `> Important: Pay attention! It's important.` will render this:\n",
    "\n",
    "> Important: Pay attention! It's important.\n",
    "\n",
    "\n",
    "\n",
    "Typing `> Tip: This is my tip.` will render this:\n",
    "\n",
    "> Tip: This is my tip.\n",
    "\n",
    "\n",
    "\n",
    "Typing `> Note: Take note of this.` will render this:\n",
    "\n",
    "> Note: Take note of this.\n",
    "\n",
    "\n",
    "\n",
    "Typing `> Note: A doc link to [an example website: fast.ai](https://www.fast.ai/) should also work fine.` will render in the docs:\n",
    "\n",
    "> Note: A doc link to [an example website: fast.ai](https://www.fast.ai/) should also work fine."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## More Examples\n",
    "\n",
    "This [tutorial](https://fastpages.fast.ai/2020/02/20/test.html) contains more examples of what you can do with notebooks.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How fastpages Converts Notebooks to Blog Posts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "fastpages uses [nbdev](https://nbdev.fast.ai/index.html) to power the conversion process of Jupyter Notebooks to blog posts.  When you save a notebook into the `/_notebooks` folder of your repository, GitHub Actions applies `nbdev` against those notebooks automatically.  The same process occurs when you save Word documents or markdown files into the `_word` or `_posts` directory, respectively.\n",
    "\n",
    "We will discuss how GitHub Actions work in a follow up blog post."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Resources & Next Steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We highly encourage you to start blogging with `fastpages`!  Some resources that may be helpful:\n",
    "\n",
    "- [fastpages repo](https://github.com/fastai/fastpages) - this is where you can go to create your own fastpages blog!\n",
    "- Fastai forums - [nbdev & blogging category](https://forums.fast.ai/c/fastai-users/nbdev/).  You can ask questions about fastpages here, as well as suggest new features.\n",
    "- [nbdev](https://github.com/fastai/nbdev): this project powers the conversion of Jupyter notebooks to blog posts.\n",
    "\n",
    "If you end up writing a blog post using fastpages, please let us know on Twitter: [@jeremyphoward](https://twitter.com/jeremyphoward), [@HamelHusain](https://twitter.com/hamelhusain)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "visualization-curriculum-gF8wUgMm",
   "language": "python",
   "name": "visualization-curriculum-gf8wugmm"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}