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 | ||
| 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 | ||
| 656af6df | 80 | => gemini://r.bdr.sh/page.gmi |
| 7f4a6af9 RBR |
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 | ||
| b0377694 | 120 | * 1.3.1 Don't add closing slash to line breaks |
| 7f4a6af9 RBR |
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. |