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

... / ...

Commit	Line	Data
	1	--- title: /blog.html
	2	--- description: Blog is a command-line tool to author and manage a semi-ephemeral™ blog with a gemini archive.
	3	## Blog
	4
	5	Command line tool to author and manage a semi-ephemeral™ blog with a gemini archive.
	6
	7	=> https://git.r.bdr.sh/rbdr/blog view source @ git.r.bdr.sh
	8	=> https://git.sr.ht/~rbdr/blog source mirror @ sourcehut
	9
	10	## Install
	11
	12	At the moment only installation from source is available. Clone this repository and run `pnpm install -g .`. This will add the `blog` command to your shell.
	13
	14	## Usage I: Authoring
	15
	16	### Add a New Post
	17
	18	Create a `.gmi` gemini file.
	19
	20	You can add this to the blog using the following command:
	21	```
	22	blog --add path/to/blog_post.gmi
	23	```
	24
	25	This it will shift all posts and remove the oldest one if the limit of posts is reached (defualts to 3). This will also regenerate the static files.
	26
	27	### Updating the Latest post
	28
	29	If you need to make corrections to the latest post, use:
	30
	31	```
	32	blog --update path/to/blog_post.gmi
	33	```
	34
	35	This will replace the latest with the contents of the `path` without shifting the existing entries. It will also regenerate files.
	36
	37	### Regenerate Static files.
	38
	39	Adding and updating posts regenerates the blog and archive, but you can always regenerate manually (eg. if you updated your static assets or templates):
	40
	41	```
	42	blog --generate
	43	```
	44
	45	## Usage II: Publishing
	46
	47	Publishing the blog and archive requires `rsync`.
	48
	49	### Publishing the Blog
	50
	51	You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog)
	52
	53	```
	54	blog --publish <remote_server>
	55	```
	56
	57	This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog.
	58
	59	### Publishing the Archive
	60
	61	You can also publish the archive of posts as a gemlog by passing a valid rsync target
	62
	63	```
	64	blog --publish-archive <remote_server>
	65	```
	66
	67	This will include all the posts in gemtext format.
	68
	69	## Usage III: Source Control
	70
	71	Blog supports saving snapshots of the blog in git, and you can add and remove remotes with the following commands:
	72
	73	```
	74	blog --add-remote <git_url>
	75	blog --remove-remote
	76	```
	77
	78	If a remote is present, it will be pulled before adding or updating, and pushed after it finishes. You can manually trigger this by calling
	79
	80	```
	81	blog --sync-up
	82	blog --sync-down
	83	```
	84
	85	The blog will always sync down before adding to avoid going out of sync.
	86
	87	IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR CHANGES WILL BE LOST
	88
	89	## Usage IV: Customizing
	90
	91	The default templates included in blog are very generic and likely not helpful for your use case. However, you can customize this freely:
	92
	93	### Using Custom Templates
	94
	95	You can override the default templates by creating a `templates` directory inside your blog data root (`$XDG_DATA_HOME/blog`).
	96
	97	For the ephemeral blog you can create `feed.xml`, `index.html`, and `index.txt` inside of `templates`. These files are then parsed with [dot][dot] and passed the following variables:
	98
	99	```
	100	it.posts <Array<Post>>
	101
	102	Post
	103	+id <String> // The numerical timestamp when the blog post was added.
	104	+createdOn <String> // The UTC String of post creation date. (only feed.xml)
	105	+title <String> // The title of the post. (only feed.xml)
	106	+raw <String> // The raw gemini text of the template.
	107	+html <String> // The parsed html generated from the gemini.
	108	```
	109
	110	To customize your gemini archive you can provide an `index.gmi` file that will be used as a template for the archive. However the data structure is different, as it's just the gemini URL strings:
	111
	112	```
	113	it.posts <Array<String>>
	114	```
	115
	116	### Using Static Files
	117
	118	Any files inside the `static` directory of your blog data root (`$XDG_DATA_HOME/blog`) will be copied as is. This is useful for any images, javascript files or stylesheets that you use in your posts or templates.
	119
	120	## Usage V: Where is Data Stored?
	121
	122	Blog uses three diretories to store data, all of them using the XDG User
	123	Directories.
	124
	125	=> https://wiki.archlinux.org/title/XDG_user_directories XDG User Directories.
	126
	127	- Configuration is stored in $XDG_CONFIG_HOME/blog
	128	- Data such as the raw blog, templates, and static files are stored in $XDG_DATA_HOME/blog
	129	- Generated "ready to upload" files are stored in $XDG_CACHE_HOME/blog
	130
	131	All of these can be overridden by environment variables.
	132
	133	## Usage VI: Configuration
	134
	135	You can control the number of posts in the ephemeral blog, and the location of
	136	all the data by using environment variables.
	137
	138	### Overriding Number of Posts
	139
	140	Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
	141	that will be kept.
	142
	143	### Overriding Configuration Directory
	144
	145	You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
	146	defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
	147	config.
	148
	149	### Overriding Data Directory
	150
	151	Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
	152	files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
	153
	154	### Overriding the location of generated files.
	155
	156	Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
	157
	158	The default is `$XDG_CACHE_HOME/blog`.
	159
	160	## Changelog
	161
	162	* 6.0.0 Use custom templates, use XDG directories.
	163	* 5.0.2 Internal template changes
	164	* 5.0.1 Dependency update
	165	* 5.0.0 Publish using rsync instead of s3
	166	* 4.0.0 Add gemini archive
	167	* 3.0.0 Add support for RSS and TXT
	168	* 2.0.0 Add support for S3 publishing
	169	* 1.0.1 Bugs and dependency fixes
	170	* 1.0.0 Initial release