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 `.gmi` gemini file.
	15
	16	You can add this to the blog using the following command, it will shift
	17	all entries and remove the oldest one if limit of posts is reached
	18	(defualts to 3):
	19
	20	```
	21	blog --add path/to/blog_post.gmi
	22	```
	23
	24	These commands will regenerate the static files. At that point you can
	25	preview your blog by serving the files on the `static` directory.
	26
	27	If you need to make corrections use:
	28
	29	```
	30	blog --update path/to/blog_post.gmi
	31	```
	32
	33	This will replace the latest with the contents of the `path` without
	34	shifting the existing entries.
	35
	36	You can always regenerate the static files by using
	37
	38	```
	39	blog --generate
	40	```
	41
	42	To publish the blog, you can select an s3 bucket and run it with:
	43
	44	```
	45	blog --publish <bucket>
	46	```
	47
	48	You can also publish the archive of posts as a gemlog, by passing a valid
	49	rsync target
	50
	51	```
	52	blog --publish-archive <rsync_target>
	53	```
	54
	55	Blog supports saving snapshots of the blog in git, and you can add and remove
	56	remotes with the following commands:
	57
	58	```
	59	blog --add-remote <git_url>
	60	blog --remove-remote
	61	```
	62
	63	If a remote is present, it will be pulled before adding or updating, and pushed
	64	after it finishes. You can manually trigger this by calling
	65
	66	```
	67	blog --sync-up
	68	blog --sync-down
	69	```
	70
	71	## Configuring
	72
	73	### Overriding Number of Posts
	74
	75	Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
	76	that will be kept.
	77
	78	### Overriding Templates
	79
	80	You can set the `BLOG_TEMPLATES_DIRECTORY` to any directory you want.
	81	The tool will expect a `feed.xml`, `index.html`, and `index.txt` files.
	82
	83	These templates are then parsed with [dot][dot] and exposes the following
	84	variables:
	85
	86	```
	87	it.posts: <Array[Post]>
	88
	89	Post
	90	+id: String // The numerical timestamp when the blog post was added.
	91	+createdOn: String // The UTC String of post creation date. (only feed.xml)
	92	+title: String // The title of the post. (only feed.xml)
	93	+raw: String // The raw gemini text of the template.
	94	+html: String // The parsed html generated from the gemini.
	95	```
	96
	97	The default is the `templates` directory inside the root of the `blog`
	98	module directory.
	99
	100	### Overriding the location of posts.
	101
	102	Setting `BLOG_POSTS_DIRECTORY` will update where the posts are saved when
	103	added. The default is the `.posts` directory inside the root of the
	104	`blog` module directory.
	105
	106	### Overriding the location of static files.
	107
	108	Setting `BLOG_STATIC_DIRECTORY` will update where static files are read
	109	from. This is also where the generated blog will be placed.
	110
	111	The default is the `static` directory inside the root of the `blog` module
	112	directory.
	113
	114	This directory should also contain files referenced in the templates, like
	115	`css`, `js` or `images`.
	116
	117	## How to publish
	118
	119	The publishing method is extremely naive. It assumes you have the
	120	AWS CLI installed and configured. It will attempt to sync the static
	121	directory to the bucket.
	122
	123	## The archive
	124
	125	The archive directory will have a full archive of the posts (currently
	126	as a gemlog format).
	127
	128	This gets updated every time you add or update a post.
	129
	130	Publishing with `--publish` will not publish the archive. Instead you should
	131	use `--publish-archive`, which will `rsync` it to the destination provided.
	132
	133	## Debugging
	134
	135	If you want to know more about what's going on when blog generates
	136	data, set the environment variable `NODE_DEBUG=blog`. This will
	137	enable the debug messages
	138
	139	[dot]: https://olado.github.io/doT/