Merge pull request jupyter-book#74 from ExecutableBookProject/myst_nb

Adding documentation for MyST notebooks

.gitignore

@@ -129,3 +129,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# VSCode config
+.vscode

docs/_toc.yml

@@ -15,6 +15,7 @@
   pages:
     - file: use/notebooks
     - file: use/myst
+    - file: use/myst-notebooks
     - file: use/layout
     - file: use/customize
     - file: use/execute
@@ -24,6 +25,7 @@
     - file: use/math
     - file: use/toc
     - file: use/page
+    - file: use/pdf
 
 - header: Reference and test pages
 - divider: true

docs/start/03_build.md

@@ -16,7 +16,7 @@ a collection of notebook/markdown files in your `mybookname/` folder, a `_toc.ym
 that defines the structure of your book, and any configuration you'd like
 in the `_config.yml` file.
 
-## Build each page's HTML
+## Build your book's HTML
 
 Now that your book's content is in your book folder and you've
 defined your book's structure in `_toc.yml`, you can build
@@ -38,35 +38,6 @@ You can also use the short-hand `jb` for `jupyter-book`. E.g.,:
 `jb build mybookname/`.
 ```
 
-## Build a PDF from your book HTML
-
-It is also possible to build a single PDF from your book's HTML. This first
-converts all of your book's content into a single HTML file, and then renders
-it as a PDF by emulating a browser from the command-line.
-
-```{warning}
-This is an experimental feature, and may change in the future.
-```
-
-````{sidebar} **Note**
-If you wish to build a PDF from your book's HTML, you will need the `pyppeteer` package.
-You can install it like so:
-
-```
-pip install pyppeteer
-```
-
-In addition, if you get errors about libraries that don't exist, check out
-[these install commands](https://circleci.com/orbs/registry/orb/threetreeslight/puppeteer)
-to see if that fixes it. We warned you it was an experimental feature :-)
-````
-
-To build a single PDF from your book's HTML, use the following command:
-
-```
-jupyter-book build mybookname/ --build pdf_html
-```
-
 ## Page caching
 
 By default, Jupyter Book will only build the HTML for pages that have

docs/test_pages/limits.md

@@ -37,23 +37,7 @@ This cheatsheet is specifically *Markdown Here's* version of Github-flavored Mar
 
 You can play around with Markdown on our [live demo page](http://www.markdown-here.com/livedemo.html).
 
-##### Table of Contents
-[Headers](#headers)
-[Emphasis](#emphasis)
-[Lists](#lists)
-[Links](#links)
-[Images](#images)
-[Code and Syntax Highlighting](#code)
-[Tables](#tables)
-[Blockquotes](#blockquotes)
-[Inline HTML](#html)
-[Horizontal Rule](#hr)
-[Line Breaks](#lines)
-[YouTube Videos](#videos)
-[TeX Mathematical Formulae](#tex)
-
-<a name="headers"/>
-
+(headers=)
 ## Headers
 
 ```bash

docs/use/citations.md

@@ -0,0 +1,68 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: '0.8'
+    jupytext_version: 1.4.1+dev
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Citations and references
+
+```{warning}
+✨✨experimental✨✨
+```
+
++++
+
+Because `jupyter-book` is built on top of Sphinx, we can use the excellent
+[sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/)
+extension to include citations and a bibliography with your book.
+
+## How to use citations
+
+Including citations with your markdown files or notebooks is done in the following
+way.
+
+1. Modify the file in `_bibliography/references.bib`. This has a few sample citations
+in bibtex form. Update as you wish!
+2. In your content, add the following text to include a citation
+
+   ```
+   {cite}`mybibtexcitation`
+   ```
+
+   For example, this text
+
+   ```
+   {cite}`holdgraf_rapid_2016`
+   ```
+
+   generates this citation: {cite}`holdgraf_rapid_2016`
+
+   You can also include multiple citations in one go, like so:
+
+   ```
+   {cite}`holdgraf_evidence_2014,holdgraf_portable_2017`
+   ```
+
+   becomes {cite}`holdgraf_evidence_2014,holdgraf_portable_2017`.
+
+3. Generate a bibliography on your page by using the following text:
+
+   ````
+   ```{bibliography} path/to/your/bibtexfile.bib
+   ```
+   ````
+
+   This will generate a bibliography for your entire bibtex file, like so:
+
+   ```{bibliography} ../references.bib
+   ```
+
+When your book is built, the bibliography and citations will now be included.