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 Configuration Directory
	79
	80	You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
	81	defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
	82	config, static files, and template
	83
	84	The tool will expect a `feed.xml`, `index.html`, and `index.txt` files in the
	85	`templates` directory inside the config directory. If they're not found it will
	86	default to the included tepmlates.
	87
	88	These templates are then parsed with [dot][dot] and exposes the following
	89	variables:
	90
	91	```
	92	it.posts: <Array[Post]>
	93
	94	Post
	95	+id: String // The numerical timestamp when the blog post was added.
	96	+createdOn: String // The UTC String of post creation date. (only feed.xml)
	97	+title: String // The title of the post. (only feed.xml)
	98	+raw: String // The raw gemini text of the template.
	99	+html: String // The parsed html generated from the gemini.
	100	```
	101
	102	### Overriding the location of posts.
	103
	104	Setting `BLOG_DATA_DIRECTORY` will update where the posts and archive are saved
	105	when added. The default is the `$XDG_DATA_HOME/blog`.
	106
	107	### Overriding the location of generated files.
	108
	109	Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
	110
	111	The default is `$XDG_CACHE_HOME/blog`.
	112
	113	This directory should also contain files referenced in the templates, like
	114	`css`, `js` or `images`.
	115
	116	## How to publish
	117
	118	The publishing method is extremely naive. It assumes you have the
	119	AWS CLI installed and configured. It will attempt to sync the static
	120	directory to the bucket.
	121
	122	## The archive
	123
	124	The archive directory will have a full archive of the posts (currently
	125	as a gemlog format).
	126
	127	This gets updated every time you add or update a post.
	128
	129	Publishing with `--publish` will not publish the archive. Instead you should
	130	use `--publish-archive`, which will `rsync` it to the destination provided.
	131
	132	## Debugging
	133
	134	If you want to know more about what's going on when blog generates
	135	data, set the environment variable `NODE_DEBUG=blog`. This will
	136	enable the debug messages
	137
	138	[dot]: https://olado.github.io/doT/