Add stable markup hooks for site themes

1 file changed, 45 insertions, 0 deletions

diff --git a/README.txt b/README.txt
index d19950e..844b6d0 100644
--- a/README.txt
+++ b/README.txt
@@ -59,6 +59,51 @@ repositories to display. A fully commented starting point with every option at
 its default is in custom/cgitrc, and MANUAL.txt documents each option in full.
 
 
+Customization
+-------------
+
+Every page is one document with the same skeleton, so a site stylesheet or
+script added through the css and js options has stable hooks to work with.
+
+* The root is div#cgit. It carries data-page with the page name, summary, log,
+  tree and so on, and data-repo with the repository url on repository pages,
+  so a rule can target one page or one repository. In embedded mode it also
+  carries the class cgit-embedded.
+* Inside it sit header#header, nav.tabs with the search form, nav.path for the
+  breadcrumb, main.content and footer.footer. Each nav, listing and option form
+  carries an aria-label, and the active tab and the current pager link carry
+  aria-current.
+* Every listing is a table.list with a second class naming it, repolist,
+  summary, refs, log or tree. Each section of a listing is a tbody named
+  repos, branches, tags, log, clone or tree, and each row carries its kind,
+  repo, branch, tag, commit, dir, blob, link or mod. A file row's link also
+  carries ext- followed by the file extension.
+* The commit and tag pages use table.commit-info, the trailer table is
+  table.commit-trailers, the diffstat is table.diffstat and each file of a diff
+  is div.file, or tbody.file in the side by side view, with the path in
+  data-path. The blob and blame pages open with div.blob-header.
+* Ages are time elements with an age-* class and the timestamp in data-ut. Line
+  numbers are anchors named n followed by the line.
+* Colours, fonts and metrics are custom properties on div#cgit, so a theme can
+  redefine those alone. Every rule in cgit.css starts with div#cgit, and a rule
+  of your own needs the same prefix to win.
+* The script exposes window.cgit.updateAges and window.cgit.highlightLines for
+  a page that changes the rows or the lines after load.
+
+A theme that only wants a colour change is a few lines.
+
+    div#cgit {
+      --link: light-dark(#7a1f1f, #f0a0a0);
+      --font-sans: Georgia, serif;
+    }
+
+    div#cgit[data-page='log'] table.list tr.commit:hover {
+      background: var(--surface);
+    }
+
+tests/t0005-markup.sh checks that every hook named here is still emitted.
+
+
 Filter extensions
 -----------------