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

... / ...

Commit	Line	Data
	1	--- title: /page.html
	2	--- description: Page is a command-line tool that can generate a static website from gemtext.
	3	## Page
	4
	5	Command line tool to generate a static website and gemini capsule from a directory with gemtext. Written in rust!
	6
	7	=> https://git.r.bdr.sh/rbdr/page view source @ git.r.bdr.sh
	8	=> https://git.sr.ht/~rbdr/page source mirror @ sourcehut
	9
	10	## Install
	11
	12	### Homebrew
	13	You can install using homebrew.
	14
	15	```
	16	% brew tap rbdr/apps git@git.sr.ht:~rbdr/homebrew-apps
	17	% brew install rbdr/apps/page
	18	```
	19
	20	### From Source
	21	Make sure you have rust and Make installed. Clone the repository, and run:
	22
	23	```
	24	% make -e profile=release
	25	```
	26
	27	Then copy the file somewhere in your PATH
	28
	29	```
	30	% cp ./target/release/page /usr/local/bin
	31	```
	32
	33	## Usage
	34
	35	Go to the directory that contains your site and run page
	36
	37	```
	38	% cd ~/projects/my_cool_page
	39	% page
	40	```
	41
	42	It will create two directories at the parent directory, they will have the same name as the current one but appending _html and _gemini respectively.
	43
	44	```
	45	% ls ~/projects
	46	my_cool_page/
	47	my_cool_page_gemini/
	48	my_cool_page_html/
	49	```
	50
	51	These pages contain the static files ready to be uploaded with a tool like scp, rsync or however you move files.
	52
	53	## The files.
	54
	55	The website directory has some requirements for page to work correctly.
	56
	57	### Gemtext
	58
	59	Any file with ending .gmi is interpreted as gemtext and will be parsed as html with the following rules:
	60
	61	* The first two lines are checked for front matter
	62	* If the first or second line starts with "--- title:", the text following will be treated as the title of the page and the line will be removed from the output.
	63	* If the first or second line starts with "--- description:", the text following will be treated as the description of the page and the line will be removed from the output.
	64	* URLs that end with the extension ".gmi" will be replaced with ".html" unless the url begins with "gemini:"
	65
	66	Example, this could be index.gmi. The first link will be converted to html but the second won't:
	67
	68	```
	69	--- title: Home
	70	--- description: Clemland is dedicated to all things sound
	71
	72	# Welcome to Clemland
	73
	74	My projects are located here:
	75
	76	=> /projects.gmi Projects
	77
	78	This is a good gemini page:
	79
	80	=> gemini://r.bdr.sh/page.gmi
	81	```
	82
	83	### The layout
	84
	85	A file called _layout.html at the root of the element. It must be present. It should include the three following keywords:
	86	* {{ title }} will get replaced with the front matter title of the gemtext file.
	87	* {{ description }} will get replaced with the front matter description of the gemtext file.
	88	* {{ content }} will get replaced with the body of the gemtext file.
	89
	90	For example:
	91
	92	```
	93	<!DOCTYPE HTML>
	94
	95	<html lang="en">
	96	<head>
	97	<meta charset="utf-8">
	98	<meta name="viewport" content="width=device-width, initial-scale=1">
	99	<meta name="author" content="Clem Fandango">
	100	<meta name="description" content="{{ description }}">
	101
	102	<title>Clemland {{ title }}</title>
	103
	104	<link rel="stylesheet" type="text/css" href="/style.css">
	105	</head>
	106	<body>
	107	<main>
	108	{{ content }}
	109	</main>
	110	</body>
	111	</html>
	112	```
	113
	114	### Static files
	115
	116	Any file that isn't gemtext or the layout will be copied as-is. This includes hidden files! The only ones that are excluded are .git and .gitignore.
	117
	118	## Changelog
	119
	120	* 1.3.1 Don't add closing slash to line breaks
	121	* 1.3.0 Adds support for specifying alt-text for preformatted text blocks.
	122	* 1.2.0 Wraps headings in a div to make certain layout operations easier.
	123	* 1.1.0 Adds front matter for title and description, generates gemini and http directories.