Markdown

You can use jupyblog to write posts in Markdown that don’t require running code snippets.

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.md
  image.png
post-b/
  post.ipynb
  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-static-post"
path_to_post.mkdir(exist_ok=True)

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

# download post
urllib.request.urlretrieve(
    "https://raw.githubusercontent.com/ploomber/jupyblog/master/examples/quick-start-static/my-post/post.md",
    path_to_post / "post.md",
)
# download image used in post
_ = urllib.request.urlretrieve(
    "https://raw.githubusercontent.com/ploomber/jupyblog/master/examples/quick-start-static/my-post/ploomber-logo.png",
    path_to_post / "ploomber-logo.png",
)

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 render your post:

%%sh
cd posts/my-static-post
jupyblog render

Input: /home/docs/checkouts/readthedocs.org/user_builds/jupyblog/checkouts/latest/doc/quick-start/posts/my-static-post
Processing post "my-static-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-static-post.md
Copying /home/docs/checkouts/readthedocs.org/user_builds/jupyblog/checkouts/latest/doc/quick-start/posts/my-static-post/ploomber-logo.png to /home/docs/checkouts/readthedocs.org/user_builds/jupyblog/checkouts/latest/doc/quick-start/posts/static/images/my-static-post/ploomber-logo.png

Since we’re not running code, the only change we’ll see is the prefix_img applied to all image paths. However, you can also customize the configuration to automate other things such as adding the author information, current date, etc.

# remove example directory
import shutil

shutil.rmtree("posts")