blog_tools/lib.rs
1//! # Blog Tools
2//!
3//! `blog-tools` is a collection of tools that helps make blogs in Rust.
4//!
5//! For this to work, you should have a folder, for instance, `blog` which serves
6//! as the root. Within this folder, you must have the following structure
7//!
8//! - blog
9//! - 2023
10//! - 2023-01-01
11//! - my_first_blog.json
12//! - my_first_blog.md
13//! - (other folders)
14//!
15//! That is, organised by year, organised by date (yyyy-mm-dd), then a `blog.md`
16//! next to a `blog.json`.
17//!
18//! The JSON must conform to the following schema
19//!
20//! ```rust,ignore
21//! {
22//! "title": String,
23//! "date": ISO 8601 Date i.e. YYYY-MM-DD,
24//! "desc": Optional<String>,
25//! "slug": String,
26//! "tags": [String],
27//! "keywords": Optional<[String]>,
28//! "canonical_link": Optional<String>,
29//! "author_name": Optional<String>,
30//! "author_webpage": Optional<String>,
31//! "last_modified": Optional<Date>, (ISO 8601)
32//! "priority": Optional<float>
33//! }
34//! ```
35//!
36//! ## Slugs
37//!
38//! In `blog-tools` all slugs are /{date}/{sub-slug}.
39//!
40//! Make sure the "slug" filed in the JSON is *just* the final sub-slug
41//!
42//! ## How This Crate is Organised
43//!
44//! There's three modules of interest
45//!
46//! - `high`
47//! - `medium`
48//! - `low`
49//!
50//! These refer to the expected RAM usage of each of these systems at runtime.
51//! Please select the style which suits the number of blogs you have the most.
52//! Do note that this crate is not intended to handle literally millions of
53//!
54//! `high` uses the most RAM by storing the entire blog in memory the whole time,
55//! the best way to do this is using a lazy static like so
56//!
57//! ```rust,ignore
58//! lazy_static! {
59//! pub static ref STATIC_BLOG_ENTRIES: HighBlog =
60//! get_high_blog(PathBuf::from(BLOG_ROOT), None, None, URL, &SitemapOptions::default());
61//! }
62//! ```
63//!
64//! `medium` stores the majority of the blog, but not the rendered HTML of the
65//! blog posts themselves. These will need to be rendered when requested
66//!
67//! ```rust,ignore
68//! lazy_static! {
69//! pub static ref STATIC_BLOG_ENTRIES: MediumBlog =
70//! get_medium_blog(PathBuf::from(BLOG_ROOT), None, None, URL, &SitemapOptions::default());
71//! }
72//!
73//! let this_blog = match all_blogs.hash.get(&complete_slug) {
74//! Some(x) => x,
75//! None => return None,
76//! };
77//!
78//! context.insert(
79//! "blog",
80//! &this_blog
81//! .render(PathBuf::from_str(BLOG_ROOT).unwrap())
82//! .unwrap(),
83//! );
84//! ```
85//! Finally, `low` stores absolutely nothing and is intended to be used to get
86//! everything at runtime.
87//!
88//! ```rust,ignore
89//! let preview = preview_blogs(PathBuf::from_str(BLOG_ROOT).unwrap(), 2, None);
90//! let tags = get_blog_tag_list(PathBuf::from_str(BLOG_ROOT).unwrap());
91//! let blog_post = render_blog_post(PathBuf::from_str(BLOG_ROOT).unwrap(), date, slug, None).unwrap();
92//! let sitemap = create_sitemap(BLOG_ROOT, URL, &SitemapOptions::default());
93//! ```
94//!
95//! This method can have serious runtime performance implecations, but might be
96//! necessary if the blog can't fit into memory
97//!
98//! ## Examples
99//!
100//! This crate comes with three examples - an identical blog website using
101//! rocket and tera templates - one using each of the modules. You can run them
102//! with
103//!
104//! ```bash,ignore
105//! cargo run --example high
106//! cargo run --example medium
107//! cargo run --example low
108//! ```
109//!
110//! You can then view the blog from localhost:8080
111//!
112#![warn(missing_docs)]
113
114mod common;
115
116mod types;
117
118pub use types::Blog;
119
120/// Sitemap related utilities can be found here. If you use `high` or `medium`
121/// then the only thing you need from here is `SitemapOptions` to configure
122/// how a sitemap is generated.
123///
124/// If you use `low` then the function `create_sitemap` can be used to
125/// generate the sitemap
126pub mod sitemap;
127
128/// `high` refers to high RAM usage - using this module you will be effectively
129/// storing the entire blog in memory at all times using a lazy static. Highest
130/// runtime performance but higest RAM usage
131///
132/// ```rust,ignore
133/// lazy_static! {
134/// pub static ref STATIC_BLOG_ENTRIES: HighBlog =
135/// get_high_blog(PathBuf::from(BLOG_ROOT), None, None, URL, &SitemapOptions::default());
136/// }
137/// ```
138pub mod high;
139
140/// `low` refers to low RAM usage - use this module when your blog is so massive
141/// you can not fit anything at all in RAM at all times, or perhaps in a serverless
142/// context. Do note that this crate is always reading files off disc - at a
143/// certain point you will probably want to start storing these in some kind
144/// of database
145///
146/// ```rust,ignore
147/// let preview = preview_blogs(PathBuf::from_str(BLOG_ROOT).unwrap(), 2, None);
148/// let tags = get_blog_tag_list(PathBuf::from_str(BLOG_ROOT).unwrap());
149/// let blog_post = render_blog_post(PathBuf::from_str(BLOG_ROOT).unwrap(), date, slug, None).unwrap();
150/// let sitemap = create_sitemap(BLOG_ROOT, URL, &SitemapOptions::default());
151/// ```
152pub mod low;
153
154/// `medium` refers to medium RAM usage - use this module when your blog is quite
155/// large, but you can fit an index in memory. You will need to render the render
156/// each blog every time you wish to display it
157///
158/// ```rust,ignore
159/// lazy_static! {
160/// pub static ref STATIC_BLOG_ENTRIES: MediumBlog =
161/// get_medium_blog(PathBuf::from(BLOG_ROOT), None, None, URL, &SitemapOptions::Default());
162/// }
163///
164/// let this_blog = match all_blogs.hash.get(&complete_slug) {
165/// Some(x) => x,
166/// None => return None,
167/// };
168///
169/// context.insert(
170/// "blog",
171/// &this_blog
172/// .render(PathBuf::from_str(BLOG_ROOT).unwrap())
173/// .unwrap(),
174/// );
175/// ```
176pub mod medium;