picoblog 0.0.2

A minimalistic static site generator written in Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# picoblog


A minimalistic static site generator written in Rust.

![Promo](https://github.com/orbitalremnant/picoblog/blob/main/promo.gif?raw=true)

`picoblog` turns a directory of Markdown and text files into a single, self-contained `index.html` with built-in search[^1] and tag filtering. It's designed for speed, simplicity, and zero-dependency deployment.

[^1]: For security reasons, search only works when the site is being server through a server.

# Key Features


-   **Single-Page Output**: Generates one `index.html` for easy hosting.
-   **Client-Side Search**: Instant full-text search with a pre-built JSON index.
-   **Tag Filtering**: Dynamically generates tag buttons to filter posts.
-   **Flexible Content**: Supports YAML frontmatter and infers metadata from filenames.
-   **Automatic Favicons**: Creates favicons from your blog's title.
-   **Highly Portable**: A single, dependency-free binary.

# Quick Start


```sh
cargo install picoblog
```

```sh
picoblog \
    --title "My Awesome Blog" \
    --description "A blog about tech and adventures." \
    --share "X:https://twitter.com/intent/tweet?url={URL}&text={TITLE}"
```

**Done!** Your new blog is ready in the `public/` directory. Open `public/index.html` in your browser to see it.

# Content Format


Place your `.md` and `.txt` files in a source directory (or many).

**Markdown with Frontmatter (`.md`):**

```txt
---
title: "My Post Title"
description: "A short summary of the post."
tags: ["rust", "tech"]
---

The main content of the post goes here.
#hashtags are also automatically detected.

```

**Plain Text (`.txt`):**

The filename is used for the title and date (e.g., `2024-10-26-quick-note.txt`).

```txt
This is a plain text post.
Line breaks are preserved.

#text #notes

```

---

## Social Sharing Links


You can generate social media sharing links for each article using the `--share` flag. This flag can be used multiple times to define different sharing providers.

### Syntax


The format for the flag is:
`--share "PROVIDER_NAME:URL_TEMPLATE"`

-   **`PROVIDER_NAME`**: The text that will be displayed for the link (e.g., "X", "LinkedIn", "Reddit").
-   **`URL_TEMPLATE`**: The sharing URL provided by the social media platform.

### Placeholders


The `URL_TEMPLATE` can contain the following placeholders, which `picoblog` will automatically replace with the article's data. The values are URL-encoded for safety.

-   **`{URL}`**: Replaced by the article's `link_url` from the frontmatter or the first URL found in the post content.
-   **`{TITLE}`**: Replaced by the article's title.
-   **`{TEXT}`**: Replaced by the raw content of the article (the Markdown or text body).

### Examples


Here are some common examples of how to use the `--share` flag:

**For X (formerly Twitter):**

```bash
--share "X:https://twitter.com/intent/tweet?url={URL}&text={TITLE}"
```

**For LinkedIn:**

```bash
--share "LinkedIn:https://www.linkedin.com/sharing/share-offsite/?url={URL}"
```

**For Reddit:**

```bash
--share "Reddit:https://www.reddit.com/submit?url={URL}&title={TITLE}"
```

**For Email:**

```bash
--share "Email:mailto:?subject={TITLE}&body={TEXT}%0A%0A{URL}"
```

**Combining Multiple Providers:**

To include links for X, LinkedIn, and Reddit, simply use the flag for each one:

```bash
./target/release/picoblog \
    --share "X:https://twitter.com/intent/tweet?url={URL}&text={TITLE}" \
    --share "LinkedIn:https://www.linkedin.com/sharing/share-offsite/?url={URL}" \
    --share "Reddit:https://www.reddit.com/submit?url={URL}&title={TITLE}"
```