|
5 | 5 | "id": "331a9e51-3d6b-42c2-940d-fbc44bf81e26", |
6 | 6 | "metadata": {}, |
7 | 7 | "source": [ |
8 | | - "# Blogging With Notebooks\n", |
| 8 | + "# Blogging\n", |
9 | 9 | "\n", |
10 | | - "> Creating a blog with notebooks" |
| 10 | + "> Creating a blog with notebooks\n", |
| 11 | + "- order: 5" |
11 | 12 | ] |
12 | 13 | }, |
13 | 14 | { |
|
17 | 18 | "source": [ |
18 | 19 | "## Background\n", |
19 | 20 | "\n", |
20 | | - "Blogging with notebooks can often a dramatic quality of life improvement over writing in Markdown, especially for blog posts that contain code. Previously, there were no static site generators that supported Jupyter Notebooks as a first-class authoring medium. This previously led us to create [fastpages](https://github.com/fastai/fastpages) (now deprecated), which extended [Jekyll](https://jekyllrb.com/) to enable blogging directly with Jupyter. \n", |
| 21 | + "Blogging with notebooks can offer a dramatic quality of life improvement over writing in Markdown, especially for blog posts that contain code. Previously, there were no static site generators that supported Jupyter Notebooks as a first-class authoring medium. This previously led us to create [fastpages](https://github.com/fastai/fastpages) (now deprecated), which extended [Jekyll](https://jekyllrb.com/) to enable blogging directly with Jupyter. \n", |
21 | 22 | "\n", |
22 | 23 | "## Enter Quarto\n", |
23 | 24 | "\n", |
|
28 | 29 | "- [The Quarto Homepage](https://quarto.org/)\n", |
29 | 30 | "- [Creating A Blog With Quarto](https://quarto.org/docs/websites/website-blog.html): This page helps you get started with creating a blog.\n", |
30 | 31 | "- [A Gallery of Quarto Sites](https://quarto.org/docs/gallery/): Good reference examples of using Quarto.\n", |
31 | | - "- [The Quarto Website](https://github.com/quarto-dev/quarto-web): The Quarto website is built with Quarto and they use lots of the advanced functionality of Quarto. It is instructive to look through this project to understand how Quarto works.\n", |
| 32 | + "- [The Quarto Website](https://github.com/quarto-dev/quarto-web): The Quarto website is built with Quarto and they use some of its advanced functionality. It is instructive to look through this project to understand how Quarto works.\n", |
32 | 33 | "\n", |
33 | 34 | ":::{.callout-note}\n", |
34 | 35 | "\n", |
|
51 | 52 | "source": [ |
52 | 53 | "## Migrating From fastpages\n", |
53 | 54 | "\n", |
54 | | - "If you previously had a fastpages site, we offer some utilities to help you migrate to Quarto. **The migration is not holistic: you will likely have to manually correct some things that we are not able to automate.**\n", |
| 55 | + "If you previously had a fastpages site, we offer some utilities to help migrate you to Quarto. **The migration is not holistic: you will likely have to manually correct some things that we are not able to automate.**\n", |
55 | 56 | "\n", |
56 | 57 | "Instructions:\n", |
57 | 58 | "\n", |
58 | 59 | "1. [Install Quarto](https://quarto.org/docs/get-started/)\n", |
59 | 60 | "2. Create a new repo or directory to migrate your blog to\n", |
60 | 61 | "\n", |
61 | | - "3. In this new repo, create a quarto blog and install required extensions with the following terminal commands, this will create a minimal project structure with a couple of example blog posts: \n", |
| 62 | + "3. In this new repo, create a quarto blog and install required extensions with the following terminal commands. This will create a minimal project structure for you:\n", |
62 | 63 | "\n", |
63 | 64 | "```bash\n", |
64 | 65 | "quarto create-project --type website:blog .\n", |
65 | 66 | "quarto install extension quarto-ext/video\n", |
66 | 67 | "```\n", |
67 | 68 | "\n", |
| 69 | + "5. Your new repo will have a `posts/` directory. This is where you will copy all of your notebook and markdown posts from fastpages. For example, let's say your fastpages blog repo is in a sibling directory located at `../blog/`, you would copy all the relevant posts like this: \n", |
| 70 | + "\n", |
68 | 71 | ":::{.callout-important}\n", |
69 | 72 | "\n", |
70 | 73 | "Make sure you are in root of your quarto directory before executing the below commands. Furthermore, change the commands as appropriate depending on the location of your fastpages repo relative to your current directory.\n", |
71 | 74 | "\n", |
72 | 75 | ":::\n", |
73 | 76 | "\n", |
74 | | - "5. Your new repo will have a `posts/` directory. This is where you will copy all of your notebook and markdown posts from fastpages. For example, let's say your fastpages blog repo is in a sibling directory located at `../blog/`, you would copy all the relevant posts like this: \n", |
75 | | - "\n", |
76 | 77 | "```bash\n", |
77 | 78 | "cp -r ../blog/_notebooks/* posts\n", |
78 | 79 | "cp -r ../blog/_posts/* posts\n", |
79 | 80 | "```\n", |
80 | 81 | "\n", |
81 | | - "6. Copy all images associated with your posts into the `posts/` directory. We have to get our images from several places (due to the way Jekyll works):\n", |
| 82 | + "6. Copy all images associated with your posts into the `posts/` directory. We have to get our images from several places (due to the way Jekyll and fastpages work):\n", |
82 | 83 | "\n", |
83 | 84 | "```bash\n", |
84 | 85 | "cp ../blog/images/* posts\n", |
|
127 | 128 | "- `./about.qmd`: Add some information about yourself.\n", |
128 | 129 | "- `./profile.jpg`: optionally change the profile picture.\n", |
129 | 130 | "\n", |
130 | | - "9. Preview your site with the command `quarto preview`, and make any necessary adjustments and fix for broken links or Jekyll shortcodes (things with `{% ... %}`) that need to be converted to Quarto. \n", |
| 131 | + "9. Preview your site with the command `quarto preview`, and make any necessary adjustments and fix for broken links or Jekyll shortcodes (things with `{% ... %}`) that need to be converted to Quarto. Search the [the Quarto documentation](https://quarto.org/) if you need help locating specific Quarto features.\n", |
131 | 132 | "\n", |
132 | 133 | "## Publishing Your Blog\n", |
133 | 134 | "\n", |
134 | 135 | "::: {.callout-warning}\n", |
135 | | - "_This section is for stand-alone blogs that are not part of a nbdev documentation site. If you want to create a blog within a nbdev documentation site, see the section [Creating a blog Within a nbdev Project](#creating-a-blog-within-a-nbdev-project)._\n", |
| 136 | + "_This section is for stand-alone blogs that are not part of a nbdev documentation site. If you want to create a blog within a nbdev documentation site, see [this section](#creating-a-blog-within-a-nbdev-project)._\n", |
136 | 137 | ":::\n", |
137 | 138 | "\n", |
138 | 139 | "You can publish your site with the `quarto publish` command. See [the docs](https://quarto.org/docs/publishing/) for more details. \n", |
|
148 | 149 | "\n", |
149 | 150 | "## Creating A Blog Within A nbdev Project\n", |
150 | 151 | "\n", |
151 | | - "In addition to a stand-alone blog that you might build with Quarto, you might want to include a blogging site in your nbdev project itself. This website has [a blog](../blog/) as well! The easiest way to implement a blog is to emulate the directory structure of [this folder](https://github.com/fastai/nbdev/tree/master/nbs/blog). The general steps are:\n", |
| 152 | + "In addition to a stand-alone blog that you might build with Quarto, you might want to include a blogging site in your nbdev project. This website has [a blog](../blog/) as well! The easiest way to implement a blog is to emulate the directory structure of [this folder](https://github.com/fastai/nbdev/tree/master/nbs/blog). The general steps are:\n", |
152 | 153 | "\n", |
153 | 154 | "1. **Create a `blog/` directory in your notebooks folder.**\n", |
154 | 155 | "2. **Create a `index.qmd` file in the root of the `blog/` directory.** Here [is an example](https://github.com/fastai/nbdev/blob/master/nbs/blog/index.qmd).\n", |
155 | 156 | "\n", |
156 | 157 | "\n", |
157 | | - "The frontmatter the `index.qmd` file signals to Quarto that you intend to create a blog. For example, here is our front matter:\n", |
| 158 | + "The frontmatter the `index.qmd` file signals to Quarto that you intend to create a blog. For example, here is [our front matter](https://github.com/fastai/nbdev/blob/master/nbs/blog/index.qmd):\n", |
158 | 159 | "\n", |
159 | 160 | "```yaml\n", |
160 | 161 | "---\n", |
|
173 | 174 | "\n", |
174 | 175 | "The `listing:` field specifies how you want to structure your blog. Feel free to copy ours as-is, but we encourage you to [consult the documentation](https://quarto.org/docs/websites/website-blog.html) for additional options.\n", |
175 | 176 | "\n", |
176 | | - "3. **Create a folder for each blog post**: This is not strictly required, but we recommend this as a way to keep your blog posts and related assets (pictures, videos etc) organized. \n", |
| 177 | + "3. **Create a link to your blog on your site's navbar so people can find it**: To add a link to your blog on your site's navbar, you must edit the navbar section of `_quarto.yml` to include a link to your blog's listing page, which is `blog/index.qmd` in our example. For nbdev, the relevant part of our [`_quarto.yml`](https://github.com/fastai/nbdev/blob/master/nbs/_quarto.yml) file looks like this:\n", |
| 178 | + "[The yaml snippet shown below is an abbreviated version of nbdev's [`_quarto.yml`](# An abbreviated version of https://github.com/fastai/nbdev/blob/master/nbs/_quarto.yml) file.]{.aside}\n", |
| 179 | + "```yaml\n", |
| 180 | + "website:\n", |
| 181 | + " navbar:\n", |
| 182 | + " left:\n", |
| 183 | + " - text: \"Blog\"\n", |
| 184 | + " href: blog/index.qmd\n", |
| 185 | + "```\n", |
177 | 186 | "\n", |
178 | | - "4. **Create your first blog post**: You can emulate our example or create your own. In each folder, create a `index.qmd` or `index.ipynb` file. You can also put images and related assets in the same folder.\n", |
| 187 | + "\n", |
| 188 | + "You can read more about the navbar in the [Quarto docs](https://quarto.org/docs/websites/website-navigation.html#top-navigation).\n", |
| 189 | + "\n", |
| 190 | + "4. **Create a folder for each blog post**: This is not strictly required, but we recommend this as a way to keep your blog posts and related assets (pictures, videos etc) organized. \n", |
| 191 | + "\n", |
| 192 | + "5. **Create your first blog post**: You can emulate our example or create your own. In each folder, create a `index.qmd` or `index.ipynb` file. You can also put images and related assets in the same folder.\n", |
179 | 193 | "\n", |
180 | 194 | "\n", |
181 | 195 | "### Folder Structure\n", |
182 | 196 | "\n", |
183 | | - "Below is an overview of the general folder structure a blog within an nbdev site\n", |
| 197 | + "Below is an overview of the general folder structure for a blog within a nbdev site:\n", |
184 | 198 | "\n", |
185 | 199 | "```\n", |
186 | 200 | "nbs/blog\n", |
|
199 | 213 | "\n", |
200 | 214 | "- `nbs/blog`: this is the folder inside your notebook folder that contains the blog.\n", |
201 | 215 | "- `index.qmd`: this is at the root of your blog folder and is the listings page for your blog.\n", |
202 | | - "- `posts/`: this contains subdirectories, one for each blog post.\n", |
| 216 | + "- `posts/`: this a subdirectory for each blog post.\n", |
203 | 217 | "- `YYYY-MM-DD-.../index.{qmd,ipynb}`: this is where you author the content of each individual blog post.\n", |
204 | 218 | "\n", |
205 | 219 | "### Special Considerations For nbdev blogs\n", |
206 | 220 | "\n", |
207 | | - "In contrast to standalone Quarto blogs, when you embed a Blog in a nbdev website there are the following differences:\n", |
| 221 | + "In contrast to standalone Quarto blogs, when you embed a blog in a nbdev website there are the following differences:\n", |
208 | 222 | "\n", |
209 | | - "- You can use all [nbdev directives](../explanations/directives.ipynb) in addition to Quarto ones. Generally speaking, any kind of nbdev feature or shortcut will be availble in your nbdev blog in the same way they work for other pages.\n", |
| 223 | + "- You can use all [nbdev directives](../explanations/directives.ipynb) in addition to Quarto ones. All nbdev features will be available in your nbdev blog in the same way they work for other pages.\n", |
210 | 224 | "- Your site will automatically deploy with GitHub Actions or whatever deployment mechanism you have for your nbdev site, so you do not have to use `quarto publish`. " |
211 | 225 | ] |
212 | 226 | }, |
|
239 | 253 | "\n", |
240 | 254 | " You will have to do some manual work to make sure everything looks and works the same, including converting Jekyll shortcodes to equivalent Quarto commands. However, we have automated the biggest aspects for you. Please see [Migrating from fastpages](#migrating-from-fastpages) with instructions.\n", |
241 | 255 | "\n", |
242 | | - "3. **I cannot find something in Quarto that does `#collapse_output`**\n", |
| 256 | + "3. **I cannot find something in Quarto that does what `#collapse_output` did in fastpages**\n", |
243 | 257 | "\n", |
244 | 258 | " Correct, this is a feature that isn't supported in Quarto yet. \n", |
245 | 259 | "\n", |
|
269 | 283 | " \n", |
270 | 284 | "8. **What does nbdev have to do with Quarto?**.\n", |
271 | 285 | "\n", |
272 | | - " For just blogging, nothing! You can use Quarto for blogging without worrying about nbdev. In the past, we maintained a nbdev related project called [fastpages](https://github.com/fastai/fastpages), and are recommending that people migrate to Quarto if possible. Furthermore, nbdev is built on top of Quart,o which means much of the functionality is similar and we wanted to make the nbdev community aware of how to use Quarto for blogging. Finally, you can incorporate blogs into a nbdev project site, which we discuss in [Blog in nbdev docs](#blog-in-nbdev-docs)." |
| 286 | + " For just blogging, nothing! You can use Quarto for blogging without worrying about nbdev. In the past, we maintained a nbdev related project called [fastpages](https://github.com/fastai/fastpages), and are recommending that people migrate to Quarto if possible. Furthermore, nbdev is built on top of Quart,o which means much of the functionality is similar and we wanted to make the nbdev community aware of how to use Quarto for blogging. Finally, you can incorporate blogs into a nbdev project site, which we discuss in [Blog in nbdev docs](#blog-in-nbdev-docs).\n", |
| 287 | + " \n", |
| 288 | + "9. **For stand alone blogs, why are you directing us to Quarto, can I just use nbdev?**\n", |
| 289 | + "\n", |
| 290 | + " nbdev is built on top of Quarto. For the purposes of blogging, Quarto provides most of what you need, and adding nbdev is of little additional benefit if all you want to do is to create a blogging site. We decided to keep things simple and let people use Quarto directly instead of trying to abstract aspects of Quarto for blogging. Furthermore, having some knowledge of Quarto can be very helpful in using nbdev!. Lastly, you can still use some nbdev features in your blog, which are listed in [this article](modular_nbdev.ipynb)." |
273 | 291 | ] |
274 | 292 | }, |
275 | 293 | { |
|
0 commit comments