Markdown

Installation

%pip install jupyblog --quiet

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

Example

Let’s download the example files:

1. jupyblog.yaml: configuration file

2. post.md: post content

3. ploomber-logo.png: sample image

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",
)

We stored everything in a posts/ directory, this is the structure that jupyblog expectds: a directory with a jupyblog.yaml configuration file and one directory per post:

%ls posts/

jupyblog.yaml  my-static-post/

The configuration file sets a few settings:

• path_to_posts: Where to store the rendered posts (path is relative to the posts/ directory

• path_to_static: Where to store any images referenced in the post (path is relative to the posts/ directory

• prefix_img: A prefix that will be applied to all image paths (e.g., ![img](path.png) becomes ![img](/images/blog/path.png))

These settings will depend on our blog structure configuration, these values are examples.

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

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

Posts are organized in folders. Inside each folder we have a post file (post.md in this case) and any associated images. This means that you can reference your images with relative paths (e.g., ![img](ploomber-logo.png)) so you can preview them with any Markdown editor.

%ls posts/my-static-post/

ploomber-logo.png  post.md

Let’s look at the contents of our post:

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

---
title: My post
jupyblog:
    execute_code: false
description: Some post description
---

## My section

This sentence is some description:

```python
import load

df = load()
```

Let's show a second snippet:


```python
import clean

df_clean = clean(df)
```

## Another section

Next, an image:

![ploomber-logo](ploomber-logo.png)

Note that the Markdown file contains a configuration section at the top:

---
title: My post
jupyblog:
    execute_code: false
description: Some post description
---

Title is the title of the post, the jupyblog section can be copied as-is, and description is the blog post description (a one-sentence summary).

Let’s now render the post:

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

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

In our configuration file (jupyblog.yaml), we said we wanted to store our rendered posts in the content/posts/ directory, let’s look at it:

%ls posts/content/posts/

my-static-post.md

Let’s look at our rendered post. You’ll see that the content is the same, except the prefix_img (/images/blog was added):

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

---
description: Some post description
images:
- /images/blog/my-static-post/ploomber-logo.png
jupyblog:
  execute_code: false
  version_jupysql: 0.0.15dev
title: My post
---

## My section

This sentence is some description:

```python
import load

df = load()
```

Let's show a second snippet:


```python
import clean

df_clean = clean(df)
```

## Another section

Next, an image:

![ploomber-logo](/images/blog/my-static-post/ploomber-logo.png)

# remove example directory
import shutil

shutil.rmtree("posts")