Lady’s Gitweb - Shrine-XSLT/blob - README.markdown

   1 # X·S·L·T Shrine Generator
   2
   3 A very lightweight and oldweb static site generator, mainly targeted
   4 at eliminating the need for `<iframe>` headers and footers without
   5 substantially changing the authoring flow.
   6
   7 ## Features
   8
   9 - Really simple shrine generation
  10 - One command: `make`
  11
  12 ## Prerequisites
  13
  14 These things come pre·installed on many platforms :—
  15
  16 - G·N·U `make` (run `make --version` to see if it is installed)
  17 - `xsltproc` (run `xsltproc --version` to see if it is installed)
  18
  19 You will also need to know how to write X·M·L, and how to navigate to a
  20 directory via the command line and run `make`.
  21
  22 Finally, you will need a copy of this repository, which serves as a
  23 template.
  24
  25 ## Basic Usage
  26
  27 In the `sources/` directory, create X·M·L files containing the unique
  28 content of your pages. Generally you will want a general landing page
  29 called `index.xml`, and a variety of other subpages. The root element
  30 of these files should typically be an H·T·M·L `<article>` element
  31 (remember to declare the X·H·T·M·L namespace!), and you should give it
  32 a `@lang` attribute as well. An example is provided.
  33
  34 The `@data-shrine-header` and `@data-shrine-footer` attributes on the
  35 root elements of your pages specify the names of the header and footer
  36 to use on the page. You can use headers and footers to supply page
  37 navigation, branding, and so forth. For each header and footer you
  38 specify, you will need to create a corresponding `$-header.xml` or
  39 `$-footer.xml` (where `$` is the header/footer name) which provides
  40 the contents. These files should be placed in *this* (repository root)
  41 directory, not in `sources/`.
  42
  43 The `template.xml` file in this directory contains the main page
  44 template, and you should edit it to add styling and so forth to your
  45 page. The `<shrine-header>`, `<shrine-content>`, and `<shrine-footer>`
  46 elements will be replaced by the page header, content, and footer,
  47 respectively.
  48
  49 Finally, just run `make` from this directory, and H·T·M·L files
  50 corresponding to your source files will be created in the `public/`
  51 directory (which you can then serve statically from your server).
  52
  53 ## Atom Feeds
  54
  55 Any `.atom` files you provide will automatically be filled out with
  56 `<id>`s, `<updated>` values, and other necessary information before
  57 being copied to the destination location. If you wish to use this
  58 feature, you will need to provide a `BASEIRI` variable when you run
  59 `make` to allow the X·S·L·T to transform relative links into absolute
  60 ones.
  61
  62 It is recommended that :—
  63
  64 - You do *not* provide your own `<id>`s and rely on the generated ones
  65   (which will be an `oai:` URI derived from the file path).
  66
  67 - You *do* manually provide `<updated>` times for individual entries
  68   (although not the feed as a whole); otherwise every entry will be
  69   marked as updated every time the feed is generated.
  70
  71 - All `<link rel="alternate">` elements in `<entry>` elements use a
  72   relative `@href` with a leading slash. This should point to the
  73   *final* location of the entry (within, but not including, `public/`).
  74
  75 There’s an example `feed.atom` provided so you can see what this
  76   feature might look like in practice.
  77
  78 ## Notes
  79
  80 - The created files have a `.html` extension and need to be served
  81   with a `text/html` media type.
  82
  83 - Files at `sources/index.xml` and `sources/index-*.xml` will produce
  84   output at `public/%.html` (where `%` is the filename).
  85
  86 - All other files at `sources/*.xml` and `sources/*/*.xml` will produce
  87   output at `public/%/index.html` (where `%` is the filename and
  88   optional subdirectory). Only one level of subdirectory is supported.
  89
  90 - For any files at `sources/*.xml` and `sources/*/*.xml`, files in the
  91   folder with the same name (minus the `.xml`) will be copied over
  92   verbatim.
  93
  94 - The transformation doesn’t do any rewriting of links. Make sure you
  95   write them to point to the *final* location of the files, not their
  96   location within the `sources/` directory.
  97
  98 - Any `@data-*` attributes (other than `@data-shrine-*` attributes) you
  99   add to the root (`<article>`) element will be copied onto the root
 100   (`<html>`) element of the template, as will `@lang` and `@xml:lang`.
 101   You can use this to help configure page‐specific styling.
 102
 103 - You can insert content into the `<head>` of the template by setting
 104   `@slot="shrine-head"` on the appropriate elements. For example, one
 105   might customize the title of a page like
 106   `<title slot="shrine-head">My Title | My Cool Shrine</title>`.
 107
 108 - If you delete files from `sources/`, the corresponding files in
 109   `public/` will **not** be deleted and will need to be manually
 110   removed. An easy way to ensure that there are no outdated files in
 111   `public/` is just to delete the entire directory before running
 112   `make`.
 113
 114 - This repository is intended as a starting point; feel free to
 115   customize it to your needs!