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

... / ...

Commit	Line	Data
	1	# blog
	2
	3	Blog is a tool to create a semi-ephemeral™ blog with a "permanent" archive
	4	on gemini.
	5
	6	## The Ephemeral Blog.
	7
	8	Whenever you generate your blog, it will keep only the first 3 files and
	9	render an html page, an rss feed and a plaintext file.
	10
	11	Posts will disappear as you add new ones.
	12
	13	## The archive
	14
	15	Not everything is ephemeral, as we also generate an archive of the whole
	16	blog in gemini format.
	17
	18	## Installation
	19
	20	At the moment only installation from source is available. Clone this repository
	21	and run `pnpm install -g .`. This will add the `blog` command to your shell.
	22
	23	## Usage
	24
	25	### How to add a new entry
	26
	27	Create a `.gmi` gemini file.
	28
	29	You can add this to the blog using the following command, it will shift
	30	all entries and remove the oldest one if limit of posts is reached
	31	(defualts to 3):
	32
	33	```
	34	blog --add path/to/blog_post.gmi
	35	```
	36
	37	These commands will regenerate the static files. At that point you can
	38	preview your blog by serving the files on the `static` directory.
	39
	40	### How to update the latest entry
	41
	42	If you need to make corrections to the latest entry, use:
	43
	44	```
	45	blog --update path/to/blog_post.gmi
	46	```
	47
	48	This will replace the latest with the contents of the `path` without
	49	shifting the existing entries.
	50
	51	### Regenerate Static files.
	52
	53	Adding and updating regenerates the files, but you can always regenerate
	54	the static files (eg. if you updated your static assets or templates) by using:
	55
	56	```
	57	blog --generate
	58	```
	59
	60	### Publishing
	61
	62	To publish the blog, you need to have `rsync` installed and pass the address
	63	(eg. youruser@yourserver.com:/path/to/blog)
	64
	65	```
	66	blog --publish <remote_server>
	67	```
	68
	69	You can also publish the archive of posts as a gemlog by passing a valid
	70	rsync target
	71
	72	```
	73	blog --publish-archive <remote_server>
	74	```
	75
	76	### Source Control
	77
	78	Blog supports saving snapshots of the blog in git, and you can add and remove
	79	remotes with the following commands:
	80
	81	```
	82	blog --add-remote <git_url>
	83	blog --remove-remote
	84	```
	85
	86	If a remote is present, it will be pulled before adding or updating, and pushed
	87	after it finishes. You can manually trigger this by calling
	88
	89	```
	90	blog --sync-up
	91	blog --sync-down
	92	```
	93
	94	The blog will always sync down before adding to avoid going out of sync.
	95
	96	**IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR
	97	CHANGES WILL BE LOST**
	98
	99	### Using Custom Templates
	100
	101	Blog comes with built-in templates that are quite generic and likely won't
	102	fit your use case. You can override these templates by creating a `templates`
	103	directory inside your blog data root (`$XDG_DATA_HOME/blog`).
	104
	105	For the ephemeral blog you can create `feed.xml`, `index.html`, and
	106	`index.txt` inside of `templates`. These files are then parsed with [dot][dot]
	107	and passed the following variables:
	108
	109	```
	110	it.posts <Array<Post>>
	111
	112	Post
	113	+id <String> // The numerical timestamp when the blog post was added.
	114	+createdOn <String> // The UTC String of post creation date. (only feed.xml)
	115	+title <String> // The title of the post. (only feed.xml)
	116	+raw <String> // The raw gemini text of the template.
	117	+html <String> // The parsed html generated from the gemini.
	118	```
	119
	120	To customize your gemini archive you can provide an `index.gmi` file that will
	121	be used as a template for the archive. However the data structure is different,
	122	as it's just the gemini URL strings:
	123
	124	```
	125	it.posts <Array<String>>
	126	```
	127
	128	### Using Static Files
	129
	130	Any files inside the `static` directory of your blog data root
	131	(`$XDG_DATA_HOME/blog`) will be copied as is. This is useful for any images,
	132	javascript files or stylesheets that you use in your posts or templates.
	133
	134	## Configuration
	135
	136	You can control the number of posts in the ephemeral blog, and the location of
	137	configuration files using environment variables.
	138
	139	### Overriding Number of Posts
	140
	141	Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
	142	that will be kept.
	143
	144	### Overriding Configuration Directory
	145
	146	You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
	147	defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
	148	config.
	149
	150	### Overriding Data Directory
	151
	152	Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
	153	files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
	154
	155	### Overriding the location of generated files.
	156
	157	Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
	158
	159	The default is `$XDG_CACHE_HOME/blog`.
	160
	161	## Debugging
	162
	163	If you want to know more about what's going on when blog generates
	164	data, set the environment variable `NODE_DEBUG=blog`. This will
	165	enable the debug messages
	166
	167	[dot]: https://olado.github.io/doT/