git.r.bdr.sh - rbdr/blog/blame_incremental

... / ...

Commit	Line	Data
	1	# blog
	2
	3	Blog at unlimited.pizza -> Only 3 at a time.*
	4
	5	The blog is no longer 100% ephemeral. Instead it now keeps an archive
	6	in a separate folder. The archive is intended to be used as a gemlog.
	7
	8	## How to install
	9
	10	`npm install -g .` will expose the `blog` binary to your CLI.
	11
	12	## How to add a new entry
	13
	14	Create a directory with a `.gmi` gemini file, and an `/assets`
	15	directory with anything you want in there. This can be in any directory.
	16
	17	```
	18	.
	19	└── this-is-an-example-post
	20	├── assets
	21	│ └── example.wav
	22	└── this-is-an-example-post.md
	23	```
	24
	25	You can add this to the blog using the following command, it will shift
	26	all entries and remove the oldest one if limit of posts is reached
	27	(defualts to 3):
	28
	29	`blog --add path/to/blog_post`
	30
	31	These commands will regenerate the static files. At that point you can
	32	preview your blog by serving the files on the `static` directory.
	33
	34	If you need to make corrections use:
	35
	36	`blog --update path/to/blog_post`
	37
	38	This will replace the latest with the contents of the `path` without
	39	shifting the existing entries.
	40
	41	`blog --publish <bucket>`
	42
	43	Will publish the blog to the mentioned s3 bucket.
	44
	45	## Configuring
	46
	47	### Overriding Number of Posts
	48
	49	Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
	50	that will be kept.
	51
	52	### Overriding Templates
	53
	54	You can set the `BLOG_TEMPLATES_DIRECTORY` to any directory you want.
	55	The tool will expect a `feed.xml`, `index.html`, and `index.txt` files.
	56
	57	These templates are then parsed with [dot][dot] and exposes the following
	58	variables:
	59
	60	```
	61	it.posts: <Array[Post]>
	62
	63	Post
	64	+id: String // The numerical timestamp when the blog post was added.
	65	+createdOn: String // The UTC String of post creation date. (only feed.xml)
	66	+title: String // The title of the post. (only feed.xml)
	67	+raw: String // The raw gemini text of the template.
	68	+html: String // The parsed html generated from the gemini.
	69	```
	70
	71	The default is the `templates` directory inside the root of the `blog`
	72	module directory.
	73
	74	### Overriding the location of posts.
	75
	76	Setting `BLOG_POSTS_DIRECTORY` will update where the posts are saved when
	77	added. The default is the `.posts` directory inside the root of the
	78	`blog` module directory.
	79
	80	### Overriding the location of static files.
	81
	82	Setting `BLOG_STATIC_DIRECTORY` will update where static files are read
	83	from. This is also where the generated blog will be placed.
	84
	85	The default is the `static` directory inside the root of the `blog` module
	86	directory.
	87
	88	This directory should also contain files referenced in the templates, like
	89	`css`, `js` or `images`.
	90
	91	## How to publish
	92
	93	The publishing method is extremely naive. It assumes you have the
	94	AWS CLI installed and configured. It will attempt to sync the static
	95	directory to the bucket.
	96
	97	## The archive
	98
	99	The archive directory will have a full archive of the posts (currently
	100	as a gemlog format).
	101
	102	This gets updated every time you add or update a post.
	103
	104	Publishing with `--publish` will not publish the archive. Instead you should
	105	use `--publish-archive`, which will `rsync` it to the destination provided.
	106
	107	## Debugging
	108
	109	If you want to know more about what's going on when blog generates
	110	data, set the environment variable `NODE_DEBUG=blog`. This will
	111	enable the debug messages
	112
	113	[dot]: https://olado.github.io/doT/