Jupyter notebooks

Installation

%pip install jupyblog --quiet

Note: you may need to restart the kernel to use updated packages.

Layout

Projects in jupyblog must have the following structure:

jupyblog.yaml

post-a/
  post.ipynb
  image.png
post-b/
  post.md
  image.png

jupyblog.yaml is a configuration file and each folder must contain a single post along with any images in it.

Example

from pathlib import Path
import urllib.request

# create folder to store posts
path = Path("posts")
path.mkdir(exist_ok=True)

# folder to store a specific post
path_to_post = path / "my-jupyter-post"
path_to_post.mkdir(exist_ok=True)

# config file
urllib.request.urlretrieve(
    "https://raw.githubusercontent.com/ploomber/jupyblog/master/examples/quick-start-jupyter/jupyblog.yaml",
    path / "jupyblog.yaml",
)

# download post
_ = urllib.request.urlretrieve(
    "https://raw.githubusercontent.com/ploomber/jupyblog/master/examples/quick-start-jupyter/my-post/post.ipynb",
    path_to_post / "post.ipynb",
)

The jupyblog.yaml file configures where to store the rendered posts along with other settings:

print(Path("posts/jupyblog.yaml").read_text())

path_to_posts: content/posts
path_to_static: static/images
prefix_img: /images/blog

To convert your Jupyter notebook to a markdown file with outputs included:

%%sh
cd posts/my-jupyter-post
jupytext post.ipynb --to md
jupyblog render

[jupytext] Reading post.ipynb in format ipynb
[jupytext] Writing post.md
Input: /home/docs/checkouts/readthedocs.org/user_builds/jupyblog/checkouts/latest/doc/quick-start/posts/my-jupyter-post
Processing post "my-jupyter-post"
Post will be saved to /home/docs/checkouts/readthedocs.org/user_builds/jupyblog/checkouts/latest/doc/quick-start/posts/content/posts
Rendering markdown...
Making img links absolute and adding canonical name as prefix...
Output: /home/docs/checkouts/readthedocs.org/user_builds/jupyblog/checkouts/latest/doc/quick-start/posts/content/posts/my-jupyter-post.md
Deploy Flask apps for free on Ploomber Cloud! Learn more: https://ploomber.io/s/signup

You’ll see tat the markdown post contains the output cells as new code fences:

print(Path("posts/content/posts/my-jupyter-post.md").read_text())

---
description: Some post description
jupyblog:
  execute_code: false
  version_jupysql: 0.0.15dev
title: My post
---

## My section

This sentence is some description:

```python
x = 21
y = 2

result = x * y
print(f"Result is: {result}")
```

<!-- #region -->


**Console output (1/1):**

```txt
Result is: 42
```

<!-- #endregion -->

Let's show a second snippet:


```python
x = 1
y = 41

result = x + y
print(f"Result is: {result}")
```

<!-- #region -->


**Console output (1/1):**

```txt
Result is: 42
```

<!-- #endregion -->

# remove example directory
import shutil

shutil.rmtree("posts")