@hjoncour/simpleblog
v0.5.0
Published
Portable collection logic and a React rich-content renderer for blogs and project showcases.
Maintainers
Readme
simpleblog
simpleblog is a small ESM-first library for sites that keep their content in local JSON but want reusable collection logic and a portable React renderer for rich content blocks.
It is designed for setups like:
- content stays inside the app repo
- JSON remains simple and ad hoc
- routing and page shells stay app-specific
- query logic and rich-content rendering move into a shared package
Install
npm install simpleblogThe core package works without React. simpleblog/react expects react >= 18.
Core Usage
import {createCollection} from 'simpleblog';
const posts = createCollection({
name: 'posts',
identity: 'slug',
load: async (locale: string) => {
const module = await import(`./content/${locale}/posts.json`);
return module.default;
},
defaultSort: {by: 'date', direction: 'desc'},
recentSort: {by: 'date', direction: 'desc'},
searchFields: ['title', 'preview', 'tags', 'content'],
defaultTagMode: 'or',
});
const allPosts = await posts.list({locale: 'en'});
const recentPosts = await posts.recent({locale: 'en', limit: 4});
const currentPost = await posts.get('hello-world', {locale: 'en'});React Renderer
Built-in blocks can stay ad hoc:
[
{"h2": "Hello"},
{"p": "Lorem ipsum dolor sit amet.\n[Read more](https://example.com)"},
{"ul": ["First item", "Second item with a [link](https://example.com)"]},
{"img": "https://picsum.photos/1200/600"}
]video takes a URL, or an object with playback options:
[
{"video": "https://res.cloudinary.com/demo/video/upload/f_auto,q_auto/clip.mp4"},
{
"video": {
"src": "https://res.cloudinary.com/demo/video/upload/f_auto,q_auto/clip.mp4",
"poster": "https://res.cloudinary.com/demo/video/upload/so_0/clip.jpg",
"autoplay": true,
"loop": true
}
}
]controls defaults to true unless autoplay is set, muted defaults to the value of autoplay (browsers block unmuted autoplay), playsInline defaults to true, and preload defaults to "metadata". src and poster both go through resolveAsset.
ul and ol take an array of items. Items are strings, or objects with text plus optional className / style:
[
{
"ol": [
"Plain item",
{"text": "Highlighted item", "style": {"fontWeight": 700}}
]
}
]table takes an array of rows for a plain grid, or an object when it needs headers, a caption, a footer, or styling:
[
{"table": [["Lorem", "Ipsum"], ["Dolor", "Sit"]]},
{
"table": {
"caption": "Lorem ipsum per column",
"headers": ["Name", "Count", "Notes"],
"align": ["left", "right"],
"rows": [
["Lorem", 12, "Plain row with a [link](https://example.com)"],
{
"cells": [{"text": "Ipsum", "header": true}, {"text": "Spans two columns", "colSpan": 2, "style": {"fontStyle": "italic"}}],
"className": "highlighted-row"
}
],
"footer": ["Total", 12, ""],
"className": "my-table",
"style": {"fontSize": "0.875rem"},
"presentation": {
"th": {"style": {"textTransform": "uppercase"}},
"td": {"className": "my-cell"}
}
}
}
]headersandfooterare a single row;rowsis an array of rows. A row is an array of cells, or{"cells": [...]}with optionalclassName/style.- A cell is a string, a number, or an object with
textplus optionalalign,colSpan,rowSpan,header(renders a row header<th>),classNameandstyle. Cell text supports the same links and inline HTML asp. alignsetsleft/center/rightper column; a cell's ownalignwins.className/styleon the table object apply to the<table>element.presentationrestyles the parts of that one table:wrapper,table,caption,thead,tbody,tfoot,tr,th,td.sortable: trueturns the header cells into buttons that sort the body rows: ascending, descending, then back to the declared order. Values that look like numbers sort numerically, a cell'ssortValueoverrides the text used for sorting, and empty cells stay last.sortsets the initial order, e.g.{"column": 1, "direction": "desc"}. It needs aheadersrow and client-side React, and it is not meant for tables that userowSpan. The buttons are styled through thesortButtonandsortIndicatorparts.idoverrides the generated element id of the<table>; its parts derive their ids from it.
The same part names are available app-wide through the theme:
const theme: RichContentTheme = {
table: {
wrapper: {className: 'my-4 overflow-x-auto'},
th: {className: 'px-3 py-2 text-left font-semibold'},
td: {className: 'px-3 py-2'},
},
};The table sits in a horizontally scrollable wrapper so wide tables do not overflow the page on small screens.
Custom components use an explicit shape:
[
{
"component": "demoCallout",
"props": {
"title": "Lorem ipsum",
"body": "Dolor sit amet"
},
"presentation": {
"className": "my-callout",
"style": {
"marginTop": "1.5rem"
}
}
}
]import {RichContentRenderer, createComponentRegistry} from 'simpleblog/react';
const components = createComponentRegistry({
demoCallout: DemoCallout,
});
<RichContentRenderer content={post.content} components={components} />;Styling
Styling merges in this order:
- library defaults
- app-level theme overrides
- per-block
presentationfor custom components orclassName/stylefor ad hoc built-ins
The renderer supports both className and inline style.
For tables the order is: library defaults, theme.table, the table's own presentation, column align, then the row's or cell's className / style.
Element ids
Every element the renderer outputs has a deterministic id built from the block's position: simpleblog-root, simpleblog-block-3, simpleblog-block-3-h2, simpleblog-block-3-ul-item-0, simpleblog-block-3-table-row-1-cell-0, and so on. Pass idPrefix to replace the simpleblog prefix, which is required to keep ids unique when more than one RichContentRenderer is on the same page.
HTML Safety
HTML is sanitized by default. Trusted HTML is available via htmlMode="trusted" when the content source is fully trusted.
Examples
Example JSON lives in examples/posts.en.json and examples/projects.en.json.
