demo: simplify documentation for writing content in Jupyter

exampleSite/content/post/jupyter/academic.ipynb → exampleSite/content/post/jupyter/index.ipynb

@@ -1,5 +1,37 @@
 {
  "cells": [
+  {
+   "cell_type": "raw",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "title: Display Jupyter Notebooks with Academic\n",
+    "subtitle: Learn how to blog in Academic using Jupyter notebooks\n",
+    "summary: Learn how to blog in Academic using Jupyter notebooks\n",
+    "authors:\n",
+    "- admin\n",
+    "tags: []\n",
+    "categories: []\n",
+    "date: \"2019-02-05T00:00:00Z\"\n",
+    "featured: false\n",
+    "draft: false\n",
+    "\n",
+    "# Featured image\n",
+    "# To use, add an image named `featured.jpg/png` to your page's folder. \n",
+    "image:\n",
+    "  caption: \"\"\n",
+    "  focal_point: \"\"\n",
+    "\n",
+    "# Projects (optional).\n",
+    "#   Associate this post with one or more of your projects.\n",
+    "#   Simply enter your project's folder or file name without extension.\n",
+    "#   E.g. `projects = [\"internal-project\"]` references \n",
+    "#   `content/project/deep-learning/index.md`.\n",
+    "#   Otherwise, set `projects = []`.\n",
+    "projects: []\n",
+    "---"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 5,
@@ -43,20 +75,20 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Install Python and Jupyter\n",
+    "## Install Python and JupyterLab\n",
     "\n",
-    "[Install Anaconda](https://www.anaconda.com/distribution/#download-section) which includes Python 3 and Jupyter notebook.\n",
+    "[Install Anaconda](https://www.anaconda.com/distribution/#download-section) which includes Python 3 and JupyterLab.\n",
     "\n",
-    "Otherwise, for advanced users, install Jupyter notebook with `pip3 install jupyter`."
+    "Alternatively, install JupyterLab with `pip3 install jupyterlab`."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Create a new blog post [as usual](https://sourcethemes.com/academic/docs/managing-content/#create-a-blog-post)\n",
+    "## Create or upload a Jupyter notebook\n",
     "\n",
-    "Run the following commands in your Terminal, substituting `<MY_WEBSITE_FOLDER>` and `my-post` with the file path to your Academic website folder and a name for your blog post (without spaces), respectively:  "
+    "Run the following commands in your Terminal, substituting `<MY-WEBSITE-FOLDER>` and `<SHORT-POST-TITLE>` with the file path to your Academic website folder and a short title for your blog post (use hyphens instead of spaces), respectively:"
    ]
   },
   {
@@ -64,9 +96,9 @@
    "metadata": {},
    "source": [
     "```bash\n",
-    "cd <MY_WEBSITE_FOLDER>\n",
-    "hugo new  --kind post post/my-post\n",
-    "cd <MY_WEBSITE_FOLDER>/content/post/my-post/\n",
+    "mkdir -p <MY-WEBSITE-FOLDER>/content/post/<SHORT-POST-TITLE>/\n",
+    "cd <MY-WEBSITE-FOLDER>/content/post/<SHORT-POST-TITLE>/\n",
+    "jupyter lab index.ipynb\n",
     "```"
    ]
   },
@@ -74,18 +106,33 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Create or upload a Jupyter notebook\n",
-    "\n",
-    "Run the following command to start Jupyter within your new blog post folder. Then create a new Jupyter notebook (*New > Python Notebook*) or upload a notebook."
+    "The `jupyter` command above will launch the JupyterLab editor, allowing us to add Academic metadata and write the content."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "```bash\n",
-    "jupyter notebook\n",
-    "```"
+    "## Edit your post metadata\n",
+    "\n",
+    "The first cell of your Jupter notebook will contain your post metadata ([front matter](https://sourcethemes.com/academic/docs/front-matter/)).\n",
+    "\n",
+    "In Jupter, choose _Markdown_ as the type of the first cell and wrap your Academic metadata in three dashes, indicating that it is YAML front matter: \n",
+    "\n",
+    "```\n",
+    "---\n",
+    "title: My post's title\n",
+    "date: 2019-09-01\n",
+    "\n",
+    "# Put any other Academic metadata here...\n",
+    "---\n",
+    "```\n",
+    "\n",
+    "Edit the metadata of your post, using the [documentation](https://sourcethemes.com/academic/docs/managing-content) as a guide to the available options.\n",
+    "\n",
+    "To set a [featured image](https://sourcethemes.com/academic/docs/managing-content/#featured-image), place an image named `featured` into your post's folder.\n",
+    "\n",
+    "For other tips, such as using math, see the guide on [writing content with Academic](https://sourcethemes.com/academic/docs/writing-markdown-latex/). "
    ]
   },
   {
@@ -100,13 +147,7 @@
    "metadata": {},
    "source": [
     "```bash\n",
-    "jupyter nbconvert Untitled.ipynb --to markdown --NbConvertApp.output_files_dir=.\n",
-    "\n",
-    "# Copy the contents of Untitled.md and append it to index.md:\n",
-    "cat Untitled.md | tee -a index.md\n",
-    "\n",
-    "# Remove the temporary file:\n",
-    "rm Untitled.md\n",
+    "jupyter nbconvert index.ipynb --to markdown --NbConvertApp.output_files_dir=.\n",
     "```"
    ]
   },
@@ -114,13 +155,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Edit your post metadata\n",
-    "\n",
-    "Open `index.md` in your text editor and edit the title etc. in the [front matter](https://sourcethemes.com/academic/docs/front-matter/) according to your preference.\n",
+    "## Example\n",
     "\n",
-    "To set a [featured image](https://sourcethemes.com/academic/docs/managing-content/#featured-image), place an image named `featured` into your post's folder.\n",
-    "\n",
-    "For other tips, such as using math, see the guide on [writing content with Academic](https://sourcethemes.com/academic/docs/writing-markdown-latex/). "
+    "This post was created with Jupyter. The orginal files can be found at https://github.com/gcushen/hugo-academic/tree/master/exampleSite/content/post/jupyter"
    ]
   }
  ],
@@ -140,9 +177,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.2"
+   "version": "3.7.3"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

exampleSite/content/post/jupyter/index.md

@@ -7,6 +7,7 @@ authors:
 tags: []
 categories: []
 date: "2019-02-05T00:00:00Z"
+lastMod: "2019-09-05T00:00:00Z"
 featured: false
 draft: false
 
@@ -25,7 +26,6 @@ image:
 projects: []
 ---
 
-
 ```python
 from IPython.core.display import Image
 Image('https://www.python.org/static/community_logos/python-logo-master-v3-TM-flattened.png')
@@ -46,46 +46,51 @@ print("Welcome to Academic!")
     Welcome to Academic!
 
 
-## Install Python and Jupyter
-
-[Install Anaconda](https://www.anaconda.com/distribution/#download-section) which includes Python 3 and Jupyter notebook.
-
-Otherwise, for advanced users, install Jupyter notebook with `pip3 install jupyter`.
+## Install Python and JupyterLab
 
-## Create a new blog post [as usual](https://sourcethemes.com/academic/docs/managing-content/#create-a-blog-post)
+[Install Anaconda](https://www.anaconda.com/distribution/#download-section) which includes Python 3 and JupyterLab.
 
-Run the following commands in your Terminal, substituting `<MY_WEBSITE_FOLDER>` and `my-post` with the file path to your Academic website folder and a name for your blog post (without spaces), respectively:  
-
-```bash
-cd <MY_WEBSITE_FOLDER>
-hugo new  --kind post post/my-post
-cd <MY_WEBSITE_FOLDER>/content/post/my-post/
-```
+Alternatively, install JupyterLab with `pip3 install jupyterlab`.
 
 ## Create or upload a Jupyter notebook
 
-Run the following command to start Jupyter within your new blog post folder. Then create a new Jupyter notebook (*New > Python Notebook*) or upload a notebook.
+Run the following commands in your Terminal, substituting `<MY-WEBSITE-FOLDER>` and `<SHORT-POST-TITLE>` with the file path to your Academic website folder and a short title for your blog post (use hyphens instead of spaces), respectively:
 
 ```bash
-jupyter notebook
+mkdir -p <MY-WEBSITE-FOLDER>/content/post/<SHORT-POST-TITLE>/
+cd <MY-WEBSITE-FOLDER>/content/post/<SHORT-POST-TITLE>/
+jupyter lab index.ipynb
 ```
 
-## Convert notebook to Markdown
+The `jupyter` command above will launch the JupyterLab editor, allowing us to add Academic metadata and write the content.
 
-```bash
-jupyter nbconvert Untitled.ipynb --to markdown --NbConvertApp.output_files_dir=.
+## Edit your post metadata
 
-# Copy the contents of Untitled.md and append it to index.md:
-cat Untitled.md | tee -a index.md
+The first cell of your Jupter notebook will contain your post metadata ([front matter](https://sourcethemes.com/academic/docs/front-matter/)).
+
+In Jupter, choose _Markdown_ as the type of the first cell and wrap your Academic metadata in three dashes, indicating that it is YAML front matter: 
 
-# Remove the temporary file:
-rm Untitled.md
 ```
+---
+title: My post's title
+date: 2019-09-01
 
-## Edit your post metadata
+# Put any other Academic metadata here...
+---
+```
 
-Open `index.md` in your text editor and edit the title etc. in the [front matter](https://sourcethemes.com/academic/docs/front-matter/) according to your preference.
+Edit the metadata of your post, using the [documentation](https://sourcethemes.com/academic/docs/managing-content) as a guide to the available options.
 
 To set a [featured image](https://sourcethemes.com/academic/docs/managing-content/#featured-image), place an image named `featured` into your post's folder.
 
 For other tips, such as using math, see the guide on [writing content with Academic](https://sourcethemes.com/academic/docs/writing-markdown-latex/). 
+
+## Convert notebook to Markdown
+
+```bash
+jupyter nbconvert index.ipynb --to markdown --NbConvertApp.output_files_dir=.
+```
+
+## Example
+
+This post was created with Jupyter. The orginal files can be found at https://github.com/gcushen/hugo-academic/tree/master/exampleSite/content/post/jupyter