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
  11 - One command: `make`
  12
  13 ## Prerequisites
  14
  15 These things come pre·installed on many platforms :—
  16
  17 - G·N·U `make` (run `make --version` to see if it is installed)
  18 - `xsltproc` (run `xsltproc --version` to see if it is installed)
  19
  20 You will also need to know how to write X·M·L, and how to navigate to a
  21 directory via the command line and run `make`.
  22
  23 Finally, you will need a copy of this repository, which serves as a
  24 template.
  25
  26 ## Basic Usage
  27
  28 In the `sources/` directory, create X·M·L files containing the unique
  29 content of your pages. Generally you will want a general landing page
  30 called `index.xml`, and a variety of other subpages. The root element
  31 of these files should typically be an H·T·M·L `<article>` element
  32 (remember to declare the X·H·T·M·L namespace!), and you should give it
  33 a `@lang` attribute as well. An example is provided.
  34
  35 The `@data-shrine-header` and `@data-shrine-footer` attributes on the
  36 root elements of your pages specify the names of the header and footer
  37 to use on the page. You can use headers and footers to supply page
  38 navigation, branding, and so forth. For each header and footer you
  39 specify, you will need to create a corresponding `$-header.xml` or
  40 `$-footer.xml` (where `$` is the header/footer name) which provides
  41 the contents. These files should be placed in *this* (repository root)
  42 directory, not in `sources/`.
  43
  44 The `template.xml` file in this directory contains the main page
  45 template, and you should edit it to add styling and so forth to your
  46 page. The `<shrine-header>`, `<shrine-content>`, and `<shrine-footer>`
  47 elements will be replaced by the page header, content, and footer,
  48 respectively.
  49
  50 Finally, just run `make` from this directory, and H·T·M·L files
  51 corresponding to your source files will be created in the `public/`
  52 directory (which you can then serve statically from your server).
  53
  54 ## Notes
  55
  56 - The created files have a `.html` extension and need to be served
  57   with a `text/html` media type.
  58
  59 - Files at `sources/index.xml` and `sources/index-*.xml` will produce
  60   output at `public/%.html` (where `%` is the filename).
  61
  62 - All other files at `sources/*.xml` and `sources/*/*.xml` will produce
  63   output at `public/%/index.html` (where `%` is the filename and
  64   optional subdirectory). Only one level of subdirectory is supported.
  65
  66 - The transformation doesn’t do any rewriting of links. Make sure you
  67   write them to point to the *final* location of the files, not their
  68   location within the `sources/` directory.
  69
  70 - Any `@data-*` attributes (other than `@data-shrine-*` attributes) you
  71   add to the root (`<article>`) element will be copied onto the root
  72   (`<html>`) element of the template, as will `@lang` and `@xml:lang`.
  73   You can use this to help configure page‐specific styling.
  74
  75 - You can insert content into the `<head>` of the template by setting
  76   `@slot="shrine-head"` on the appropriate elements. For example, one
  77   might customize the title of a page like
  78   `<title slot="shrine-head">My Title | My Cool Shrine</title>`.
  79
  80 - If you delete files from `sources/`, the corresponding files in
  81   `public/` will **not** be deleted and will need to be manually
  82   removed. An easy way to ensure that there are no outdated files in
  83   `public/` is just to delete the entire directory before running
  84   `make`.
  85
  86 - This repository is intended as a starting point; feel free to
  87   customize it to your needs!