Merge pull request jupyter-book#5 from ExecutableBookProject/content

fixing citations

docs/features/citations.ipynb

@@ -6,21 +6,18 @@
    "source": [
     "# Including citations in your book\n",
     "\n",
-    "✨**experimental**✨"
+    "```{warning}\n",
+    "✨✨experimental✨✨\n",
+    "```"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Because `jupyter-book` is built on top of Jekyll, we can use the excellent\n",
-    "[jekyll-scholar](https://github.com/inukshuk/jekyll-scholar) book to\n",
-    "include citations and a bibliography with your book.\n",
-    "\n",
-    "**Note that this only works if you're building your book HTML locally and\n",
-    "hosting the HTML files online somewhere**. This can still use GitHub pages, but\n",
-    "not the auto-generation of a cite from markdown files feature of GitHub pages.\n",
-    "This is because GitHub pages doesn't include the `jekyll-scholar` plugin.\n",
+    "Because `jupyter-book` is built on top of Sphinx, we can use the excellent\n",
+    "[sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/)\n",
+    "extension to include citations and a bibliography with your book.\n",
     "\n",
     "## How to use citations\n",
     "\n",
@@ -32,42 +29,39 @@
     "2. In your content, add the following text to include a citation\n",
     "   \n",
     "   ```\n",
-    "   {% raw %}{% cite bibtex_shortname %}{% endraw %}\n",
+    "   {cite}`mybibtexcitation`\n",
+    "   ```\n",
+    "\n",
+    "   For example, this text\n",
+    "   \n",
+    "   ```\n",
+    "   {cite}`holdgraf_rapid_2016`\n",
     "   ```\n",
     "   \n",
-    "   For example, this text: `{% raw %}{% cite holdgraf_evidence_2014 %}{% endraw %}` generates this citation: {% cite holdgraf_evidence_2014 %}\n",
+    "   generates this citation: {cite}`holdgraf_rapid_2016`\n",
     "   \n",
     "   You can also include multiple citations in one go, like so:\n",
     "   \n",
-    "   `{% raw %}{% cite holdgraf_evidence_2014 holdgraf_portable_2017 ruby %}{% endraw %}` becomes {% cite holdgraf_evidence_2014 holdgraf_portable_2017 ruby %}\n",
+    "   ```\n",
+    "   {cite}`holdgraf_evidence_2014,holdgraf_portable_2017`\n",
+    "   ```\n",
+    "   \n",
+    "   becomes {cite}`holdgraf_evidence_2014,holdgraf_portable_2017`.\n",
     "   \n",
     "3. Generate a bibliography on your page by using the following text:\n",
     "\n",
+    "   ````\n",
+    "   ```{bibliography} path/to/your/bibtexfile.bib\n",
     "   ```\n",
-    "   {% raw %}{% bibliography %}{% endraw %}\n",
-    "   ```\n",
+    "   ````\n",
     "   \n",
-    "   This will generate a bibliography for your entire bibtex file. If you'd like to restrict the\n",
-    "   bibliography to only the citations you've used on a page, use the following syntax:\n",
+    "   This will generate a bibliography for your entire bibtex file, like so:\n",
     "   \n",
+    "   ```{bibliography} ../references.bib\n",
     "   ```\n",
-    "   {% raw %}{% bibliography --cited %}{% endraw %}\n",
-    "   ```\n",
-    "   \n",
-    "When your book is built, the bibliography and citations will now be included. For example,\n",
-    "see the Bibliography generated below!\n",
-    "\n",
-    "## References\n",
     "\n",
-    "{% bibliography --cited %}"
+    "When your book is built, the bibliography and citations will now be included."
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

docs/toc.yml

@@ -1,5 +1,4 @@
 - path: index
-- path: citations
 - path: guide/01_overview
   not_numbered: true
   expand_sections: true