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 ## Notes
  54
  55 - The created files have a `.html` extension and need to be served
  56   with a `text/html` media type.
  57
  58 - Files at `sources/index.xml` and `sources/index-*.xml` will produce
  59   output at `public/%.html` (where `%` is the filename).
  60
  61 - All other files at `sources/*.xml` and `sources/*/*.xml` will produce
  62   output at `public/%/index.html` (where `%` is the filename and
  63   optional subdirectory). Only one level of subdirectory is supported.
  64
  65 - For any files at `sources/*.xml` and `sources/*/*.xml`, files in the
  66   folder with the same name (minus the `.xml`) will be copied over
  67   verbatim.
  68
  69 - The transformation doesn’t do any rewriting of links. Make sure you
  70   write them to point to the *final* location of the files, not their
  71   location within the `sources/` directory.
  72
  73 - Any `@data-*` attributes (other than `@data-shrine-*` attributes) you
  74   add to the root (`<article>`) element will be copied onto the root
  75   (`<html>`) element of the template, as will `@lang` and `@xml:lang`.
  76   You can use this to help configure page‐specific styling.
  77
  78 - You can insert content into the `<head>` of the template by setting
  79   `@slot="shrine-head"` on the appropriate elements. For example, one
  80   might customize the title of a page like
  81   `<title slot="shrine-head">My Title | My Cool Shrine</title>`.
  82
  83 - If you delete files from `sources/`, the corresponding files in
  84   `public/` will **not** be deleted and will need to be manually
  85   removed. An easy way to ensure that there are no outdated files in
  86   `public/` is just to delete the entire directory before running
  87   `make`.
  88
  89 - This repository is intended as a starting point; feel free to
  90   customize it to your needs!