git.r.bdr.sh / rbdr / r.bdr.sh / blame
| Commit | Line | Data |
|---|---|---|
| 7f4a6af9 RBR |
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 | ||
| 656af6df | 7 | => https://git.r.bdr.sh/rbdr/page view source @ git.r.bdr.sh |
| 96aeed1c | 8 | => https://git.sr.ht/~rbdr/page source mirror @ sourcehut |
| 7f4a6af9 RBR |
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 | ||
| 53cf4bdd RBR |
20 | ### Prebuilt Packages |
| 21 | You can find pre-built packages for linux @ build.r.bdr.sh. There you can | |
| 22 | find a `.tar.gz` that includes only the binary, or `.rpm` and `.deb` | |
| 23 | distributions for fedora and debian that include a manpage. | |
| 24 | ||
| 25 | Binaries are provided for x86_64 and aarch64. | |
| 26 | ||
| 27 | Unstable releases are built directly from the main branch, while tagged | |
| 28 | versions have their own release and can be considered more stable. | |
| 29 | ||
| 30 | => gemini://build.r.bdr.sh/page page pre-built releases @ gemini | |
| 31 | => https://build.r.bdr.sh/page page pre-built releases @ https | |
| 32 | ||
| 7f4a6af9 RBR |
33 | ### From Source |
| 34 | Make sure you have rust and Make installed. Clone the repository, and run: | |
| 35 | ||
| 36 | ``` | |
| 37 | % make -e profile=release | |
| 38 | ``` | |
| 39 | ||
| 40 | Then copy the file somewhere in your PATH | |
| 41 | ||
| 42 | ``` | |
| 43 | % cp ./target/release/page /usr/local/bin | |
| 44 | ``` | |
| 45 | ||
| 46 | ## Usage | |
| 47 | ||
| 48 | Go to the directory that contains your site and run page | |
| 49 | ||
| 50 | ``` | |
| 51 | % cd ~/projects/my_cool_page | |
| 52 | % page | |
| 53 | ``` | |
| 54 | ||
| 55 | 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. | |
| 56 | ||
| 57 | ``` | |
| 58 | % ls ~/projects | |
| 59 | my_cool_page/ | |
| 60 | my_cool_page_gemini/ | |
| 61 | my_cool_page_html/ | |
| 62 | ``` | |
| 63 | ||
| 64 | These pages contain the static files ready to be uploaded with a tool like scp, rsync or however you move files. | |
| 65 | ||
| 66 | ## The files. | |
| 67 | ||
| 68 | The website directory has some requirements for page to work correctly. | |
| 69 | ||
| 70 | ### Gemtext | |
| 71 | ||
| 72 | Any file with ending .gmi is interpreted as gemtext and will be parsed as html with the following rules: | |
| 73 | ||
| 74 | * The first two lines are checked for front matter | |
| 75 | * 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. | |
| 76 | * 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. | |
| 77 | * URLs that end with the extension ".gmi" will be replaced with ".html" unless the url begins with "gemini:" | |
| 78 | ||
| 79 | Example, this could be index.gmi. The first link will be converted to html but the second won't: | |
| 80 | ||
| 81 | ``` | |
| 82 | --- title: Home | |
| 83 | --- description: Clemland is dedicated to all things sound | |
| 84 | ||
| 85 | # Welcome to Clemland | |
| 86 | ||
| 87 | My projects are located here: | |
| 88 | ||
| 89 | => /projects.gmi Projects | |
| 90 | ||
| 91 | This is a good gemini page: | |
| 92 | ||
| 656af6df | 93 | => gemini://r.bdr.sh/page.gmi |
| 7f4a6af9 RBR |
94 | ``` |
| 95 | ||
| 96 | ### The layout | |
| 97 | ||
| 98 | A file called _layout.html at the root of the element. It must be present. It should include the three following keywords: | |
| 99 | * {{ title }} will get replaced with the front matter title of the gemtext file. | |
| 100 | * {{ description }} will get replaced with the front matter description of the gemtext file. | |
| 101 | * {{ content }} will get replaced with the body of the gemtext file. | |
| 102 | ||
| 103 | For example: | |
| 104 | ||
| 105 | ``` | |
| 106 | <!DOCTYPE HTML> | |
| 107 | ||
| 108 | <html lang="en"> | |
| 109 | <head> | |
| 110 | <meta charset="utf-8"> | |
| 111 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 112 | <meta name="author" content="Clem Fandango"> | |
| 113 | <meta name="description" content="{{ description }}"> | |
| 114 | ||
| 115 | <title>Clemland {{ title }}</title> | |
| 116 | ||
| 117 | <link rel="stylesheet" type="text/css" href="/style.css"> | |
| 118 | </head> | |
| 119 | <body> | |
| 120 | <main> | |
| 121 | {{ content }} | |
| 122 | </main> | |
| 123 | </body> | |
| 124 | </html> | |
| 125 | ``` | |
| 126 | ||
| 127 | ### Static files | |
| 128 | ||
| 129 | 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. | |
| 130 | ||
| 131 | ## Changelog | |
| 132 | ||
| 584709f7 | 133 | * 1.3.2 Use section and p instead of div, to better support "reader mode" |
| b0377694 | 134 | * 1.3.1 Don't add closing slash to line breaks |
| 7f4a6af9 RBR |
135 | * 1.3.0 Adds support for specifying alt-text for preformatted text blocks. |
| 136 | * 1.2.0 Wraps headings in a div to make certain layout operations easier. | |
| 137 | * 1.1.0 Adds front matter for title and description, generates gemini and http directories. |