fastbook/app_blog.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "[[appendix_blog]]\n",
    "[appendix]\n",
    "[role=\"Creating a blog\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "from utils import *\n",
    "from fastai2.vision.widgets import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating a Blog"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Blogging with GitHub Pages"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Unfortunately, when it comes to blogging, it seems like you have to make a difficult decision: either use a platform that makes it easy, but subjects you and your readers to advertisements, pay walls, and fees, or spend hours setting up your own hosting and weeks learning about all kinds of intricate details. Perhaps the biggest benefit to the \"do-it-yourself\" approach is that you really owning your own posts, rather than being at the whim of a service provider, and their decisions about how to monetize your content in the future.\n",
    "\n",
    "It turns out, however, that you can have the best of both worlds! You can host on a platform called [GitHub Pages](https://pages.github.com/), which is free, has no ads or pay wall, and makes your data available in a standard way such that you can at any time move your blog to another host. But all the approaches I’ve seen to using GitHub Pages have required knowledge of the command line and arcane tools that only software developers are likely to be familiar with. For instance, GitHub's [own documentation](https://help.github.com/en/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll) on setting up a blog requires installing the Ruby programming language, using the git command line tool, copying over version numbers, and more. 17 steps in total!\n",
    "\n",
    "We’ve curated an easy approach, which allows you to use an **entirely browser-based interface** for all your blogging needs. You will be up and running with your new blog within about five minutes. It doesn’t cost anything, and you can easily add your own custom domain to it if you wish to. Here’s how to do it, using a template we've created called **fast\\_template**. (NB: be sure to check the [book website](https://book.fast.ai) for the latest blog recommendations, since new tools are always coming out; for instance, we're currently working with GitHub on creating a new tool called \"fastpages\" which is a more advanced version of `fast_template` that's particularly designed for people using Jupyter Notebooks)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating the Repository"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You’ll need an account on GitHub. So, head over there now, and create an account if you don’t have one already. Make sure that you are logged in. Normally, GitHub is used by software developers for writing code, and they use a sophisticated command line tool to work with it. But I'm going to show you an approach that doesn't use the command line at all!\n",
    "\n",
    "To get started, click on this link: [https://github.com/fastai/fast_template/generate](https://github.com/fastai/fast_template/generate) . This will allow you to create a place to store your blog, called a \"*repository*\". You will see the following screen; you have to enter your repository name using the **exact form you see below**, that is, the username you used at GitHub followed by `.github.io`.\n",
    "\n",
    "<img width=\"440\" src=\"images/fast_template/image1.png\" id=\"githup_repo\" caption=\"Creating your repository\" alt=\"Screebshot of the GitHub page for creating a new repository\">\n",
    "\n",
    "> Important: Note that if you don't use username.github.io as the name, it won't work!\n",
    "\n",
    "Once you’ve entered that, and any description you like, click on \"create repository from template\". You have the choice to make the repository \"private\" but since you are creating a blog that you want other people to read, having the underlying files publicly available hopefully won't be a problem for you.\n",
    "\n",
    "Now, let's set up your homepage!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting up Your Homepage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When readers first arrive at your blog the first thing that they will see is the content of a file called \"index.md\". This is a [markdown](https://guides.github.com/features/mastering-markdown/) file.  Markdown is a powerful yet simple way of creating formatted text, such as bullet points, italics, hyperlinks, and so forth. It is very widely used, including all the formatting in Jupyter notebooks, nearly every part of the GitHub site, and many other places all over the Internet. To create markdown text, you can just type in plain regular English. But then you can add some special characters to add special behavior. For instance, if you type a `*` character around a word or phrase then that will put it in *italics*. Let’s try it now.\n",
    "\n",
    "To open the file, click its file name in GitHub.\n",
    "\n",
    "<img width=\"140\" src=\"images/fast_template/image2.png\" alt=\"Screenshot showing a click on the index.md file\">\n",
    "\n",
    "To edit it, click on the pencil icon at the far right hand side of the\n",
    "screen.\n",
    "\n",
    "<img width=\"800\" src=\"images/fast_template/image3.png\" alt=\"Screenshot showing where to click to edit the file\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can add, edit, or replace the texts that you see. Click on the\n",
    "\"preview changes\" button to see how well your markdown text will look\n",
    "on your blog. Lines that you have added or changed will appear with a\n",
    "green bar on the left-hand side.\n",
    "\n",
    "<img width=\"350\" src=\"images/fast_template/image4.png\" alt=\"Screenshot showing where to click to preview changes\">\n",
    "\n",
    "To save your changes to your blog, you must scroll to the bottom and\n",
    "click on the \"commit changes\" green button. On GitHub, to \"commit\"\n",
    "something means to save it to the GitHub server.\n",
    "\n",
    "<img width=\"600\" src=\"images/fast_template/image5.png\" alt=\"Screenshot showing where to click to commit the changes\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, you should configure your blog’s settings. To do so, click on the\n",
    "file called \"\\_config.yml\", and then click on the edit button like you\n",
    "did for the index file above. Change the title, description, and GitHub\n",
    "username values. You need to leave the names before the colons in place\n",
    "and type your new values in after the colon and space on each line. You\n",
    "can also add to your email and Twitter username if you wish — but note\n",
    "that these will appear on your public blog if you do fill them in here.\n",
    "\n",
    "<img width=\"800\" src=\"images/fast_template/image6.png\" id=\"github_config\" caption=\"Fill the config file\" alt=\"Screenshot showing the config file and how to fill it\">\n",
    "\n",
    "After you’re done, commit your changes just like you did with the index\n",
    "file before. Then wait about a minute, whilst GitHub processes your new\n",
    "blog. Then you will be able to go to your blog in your web browser, by\n",
    "opening the URL: username.github.io (replace \"username\" with your\n",
    "GitHub username). You should see your blog!\n",
    "\n",
    "<img width=\"540\" src=\"images/fast_template/image7.png\" id=\"github_blog\" caption=\"Your blog is onlyine!\" alt=\"Screenshot showing the website username.github.io\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating Posts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you’re ready to create your first post. All your posts will go in\n",
    "the \"\\_posts\" folder. Click on that now, and then click on the \"create\n",
    "file\" button. You need to be careful to name your file in the following\n",
    "format: \"year-month-day-name.md\", where year is a four-digit number, and\n",
    "month and day are two-digit numbers. \"Name\" can be anything you want,\n",
    "that will help you remember what this post was about. The \"md\" extension\n",
    "is for markdown documents.\n",
    "\n",
    "<img width=\"440\" src=\"images/fast_template/image8.png\" alt=\"Screenshot showing the right syntax to create a new blog post\">\n",
    "\n",
    "You can then type the contents of your first post. The only rule is that\n",
    "the first line of your post must be a markdown heading. This is created\n",
    "by putting `# ` at the start of a line (that creates a level 1\n",
    "heading, which you should just use once at the start of your document;\n",
    "you create level 2 headings using `## `, level 3 with `###`, and so forth.)\n",
    "\n",
    "<img width=\"300\" src=\"images/fast_template/image9.png\" alt=\"Screenshot showing the start of a blog post\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As before, you can click on the \"preview\" button to see how your\n",
    "markdown formatting will look.\n",
    "\n",
    "<img width=\"400\" src=\"images/fast_template/image10.png\" alt=\"Screenshot showing the same blog post interpreted in HTML\">\n",
    "\n",
    "And you will need to click the \"commit new file\" button to save it to\n",
    "GitHub.\n",
    "\n",
    "<img width=\"700\" src=\"images/fast_template/image11.png\" alt=\"Screenshot showing where to click to commit the new file\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Have a look at your blog homepage again, and you will see that this post\n",
    "has now appeared! (Remember that you will need to wait a minute or so\n",
    "for GitHub to process it.)\n",
    "\n",
    "<img width=\"500\" src=\"images/fast_template/image12.png\" alt=\"Screenshot showing the first post on the blog website\">\n",
    "\n",
    "You’ll also see that we provided a sample blog post, which you can go\n",
    "ahead and delete now. Go to your posts folder, as before, and click on\n",
    "\"2020-01-14-welcome.md\". Then click on the trash icon on the far\n",
    "right.\n",
    "\n",
    "<img width=\"400\" src=\"images/fast_template/image13.png\" alt=\"Screenshot showing how to delete the mock post\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In GitHub, nothing actually changes until you commit— including deleting\n",
    "a file! So, after you click the trash icon, scroll down to the bottom\n",
    "and commit your changes.\n",
    "\n",
    "You can include images in your posts by adding a line of markdown like\n",
    "the following:\n",
    "\n",
    "    ![Image description](images/filename.jpg)\n",
    "\n",
    "For this to work, you will need to put the image inside your \"images\"\n",
    "folder. To do this, click on the images folder to go into it in GitHub,\n",
    "and then click the \"upload files\" button.\n",
    "\n",
    "<img width=\"400\" src=\"images/fast_template/image14.png\" alt=\"Screenshot showing how to upload new files\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's see how to do all of this directly from your computer."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Synchronizing GitHub and Your Computer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There’s lots of reasons you might want to copy your blog content from GitHub to your computer. Perhaps you want to read or edit your posts offline. Or maybe you’d like a backup in case something happens to your GitHub repository.\n",
    "\n",
    "GitHub does more than just let you copy your repository to your computer; it lets you *synchronize* it with your computer. So, you can make changes on GitHub, and they’ll copy over to your computer, and you can make changes on your computer, and they’ll copy over to GitHub. You can even let other people access and modify your blog, and their changes and your changes will be automatically combined together next time you sync.\n",
    "\n",
    "To make this work, you have to install an application called [GitHub Desktop](https://desktop.github.com/) to your computer. It runs on Mac, Windows, and Linux. Follow the directions at the link to install it, then when you run it it’ll ask you to login to GitHub, and then to select your repository to sync; click \"Clone a repository from the Internet\".\n",
    "\n",
    "<img src=\"images/gitblog/image1.png\" width=\"400\" alt=\"A screenshot showing how to clone your repository\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once GitHub has finished syncing your repo, you’ll be able to click \"View the files of your repository in Finder\" (or Explorer), and you’ll see the local copy of your blog! Try editing one of the files on your computer. Then return to GitHub Desktop, and you’ll see the \"Sync\" button is waiting for you to press it. When you click it, your changes will be copied over to GitHub, where you’ll see them reflected on the web site.\n",
    "\n",
    "<img src=\"images/gitblog/image2.png\" width=\"600\" alt=\"A screenshot showing the cloned repository\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you haven't used git before, GitHub Desktop and a blog is a great way to get started. As you'll discover, it's a fundamental tool used by most data scientists. Another tool that we hope you now love too is Jupyter Notebooks. And there is a way to write your blog directly with it!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Jupyter for Blogging"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also write blog posts using Jupyter Notebooks! Your markdown cells, code cells, and all outputs will appear in your exported blog post. The best way to do this may have changed by the time you are reading this book, so be sure to check out the [book website](https://book.fast.ai) for the latest information. As we write this, the easiest way to create a blog from notebooks is to use [fastpages](http://fastpages.fast.ai/), which is a more advanced version of `fast_template`. \n",
    "\n",
    "To blog with a notebook, just pop it in the `_notebooks` folder in your blog repo, and it will appear in your blog. When you write your notebook, write whatever you want your audience to see. Since most writing platforms make it much harder to include code and outputs, many of us are in a habit of including less real examples than we should. So try to get into a new habit of including lots of examples as you write.\n",
    "\n",
    "Often you'll want to hide boilerplate such as import statements. Add `#hide` to the top of any cell to make it not show up in output. Jupyter displays the result of the last line of a cell, so there's no need to include `print()`. (And including extra code that isn't needed means there's more cognitive overhead for the reader; so don't include code that you don't really need!)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "jupytext": {
   "split_at_heading": true
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}