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 preinstalled on many platforms :—
  16
  17 - G·N·U Make (run `make --version` to see if it is installed)
  18
  19 - libxslt (run `xsltproc --version` to see if it is installed)
  20
  21 You will also need to know how to write X·M·L, and how to navigate to a
  22 directory via the command line and run `make`.
  23
  24 Finally, you will need a copy of this repository, which serves as a
  25 template.
  26
  27 ## Basic Usage
  28
  29 In the `sources/` directory, create X·M·L files containing the unique
  30 content of your pages. Generally you will want a general landing page
  31 called `index.xml`, and a variety of other subpages. The root element
  32 of these files should typically be an H·T·M·L `<article>` element
  33 (remember to declare the X·H·T·M·L namespace!), and you should give it
  34 a `@lang` attribute as well. An example is provided.
  35
  36 The `@data-shrine-header` and `@data-shrine-footer` attributes on the
  37 root elements of your pages specify the names of the header and footer
  38 to use on the page. You can use headers and footers to supply page
  39 navigation, branding, and so forth. For each header and footer you
  40 specify, you will need to create a corresponding `$-header.xml` or
  41 `$-footer.xml` (where `$` is the header/footer name) which provides
  42 the contents. These files should be placed in *this* (repository root)
  43 directory, not in `sources/`.
  44
  45 The `template.xml` file in this directory contains the main page
  46 template, and you should edit it to add styling and so forth to your
  47 page. The `<shrine-header>`, `<shrine-content>`, and `<shrine-footer>`
  48 elements will be replaced by the page header, content, and footer,
  49 respectively.
  50
  51 Finally, just run `make` from this directory, and X·H·T·M·L files
  52 corresponding to your source files will be created in the `public/`
  53 directory (which you can then serve statically from your server).
  54
  55 ## Notes
  56
  57 - The created files have a `.xhtml` extension and *need* to be served
  58   with a `application/xhtml+xml` (or `application/xml`) media type. Not
  59   all servers know how to serve `.xhtml` files; if this is you, you may
  60   have better luck with `make XHTMLEXT=xml` (which will produce `.xml`
  61   files instead).
  62
  63   - Some free hosting options require that “index” pages have an
  64     extension of `.html`; these will unfortunately not work. It is
  65     possible to extend the makefile to generate `index.html` redirects
  66     to `index.xhtml` with the following code :—
  67
  68     ```make
  69     override redirects := $(patsubst public/%.$(XHTMLEXT),public/%.html,$(indices) $(pages))
  70
  71     all: $(redirects) # in addition to the previously declared prerequisites
  72
  73     $(redirects):
  74         # You may want a more involved redirect page than this, but it’s an example…
  75         echo '<!DOCTYPE html><meta http-equiv="refresh" content="0;url=./index.xhtml">' > $@
  76     ```
  77
  78     This should be considered a last resort, but it can be used to get
  79     your site working on e·g Neocities.
  80
  81 - Files at `sources/index.xml` and `sources/index-*.xml` will produce
  82   output at `public/%.xhtml` (where `%` is the filename).
  83
  84 - All other files at `sources/*.xml` and `sources/*/*.xml` will produce
  85   output at `public/%/index.xhtml` (where `%` is the filename and
  86   optional subdirectory). Only one level of subdirectory is supported.
  87
  88 - The transformation doesn’t do any rewriting of links. Make sure you
  89   write them to point to the *final* location of the files, not their
  90   location within the `sources/` directory.
  91
  92 - Any `@data-*` attributes (other than `@data-shrine-*` attributes) you
  93   add to the root (`<article>`) element will be copied onto the root
  94   (`<html>`) element of the template, as will `@lang` and `@xml:lang`.
  95   You can use this to help configure page‐specific styling.
  96
  97 - You can insert content into the `<head>` of the template by setting
  98   `@slot="shrine-head"` on the appropriate elements. For example, one
  99   might customize the title of a page like
 100   `<title slot="shrine-head">My Title | My Cool Shrine</title>`.
 101
 102 - If you delete files from `sources/`, the corresponding files in
 103   `public/` will **not** be deleted and will need to be manually
 104   removed. An easy way to ensure that there are no outdated files in
 105   `public/` is just to delete the entire directory before running
 106   `make`.
 107
 108 - This repository is intended as a starting point; feel free to
 109   customize it to your needs!