tildetown
/
tilde-wiki
1
0
Fork 1
Code Issues Pull Requests 2 Releases Wiki Activity
tilde-wiki/rfc.org

5.2 KiB
Raw Blame History

tilde-wiki RFC

Author: ~vilmibm Status: in review Date submitted: <2017-08-28 Mon>

Background

Many moons ago, I thought it would be interesting to have a user that we all shared whose home directory was a git repo. In addition to being able to modify the shared user's home directory, it had a public_html that could be filled with pretty standard wiki style content.

Users took to the html portion of the wiki user and generated a lot of useful content. the home directory / shared user aspect, however, was left untouched for years.

Thus, this RFC outlines both a shift to a formalized wiki that retains the spirit of the origial idea (git based, shell oriented, low barrier to entry) while streamlining and improving it.

Glossary

  • the wiki: the files in a git repo that constitute the town's wiki content. accessible by command line or web.
  • wiki: the wiki command, used locally to work on the wiki and publish changes
  • compiled: a purely html version of the wiki content served through a web interface
  • source: the raw files of the wiki in various formats (html, markdown, plaintext)

Proposal

  • the system path /wiki , a git repository (structure to follow).
  • the url tilde.town/wiki, configured at nginx level to serve system path /wiki/compiled
  • Deleting the wiki user and setting a redirect in nginx from /~wiki to /wiki
  • a wiki command used for initializing, adding to, and publishing the wiki
  • a convention of symlinking from ~/wiki/compiled to ~/public_html/wiki so people can preview their edits

Wiki Layout

The following is the proposed layout for the wiki with sample files

/wiki
|- .git/
|- .gitignore
|- src/
|-- toc.md
|-- header.md
|-- footer.md
|-- articles/
|---- index.md
|---- new_user.md
|---- ssh.html
|---- editors/
|------ vim.md
|------ ed.txt
|------ nano.html
|- compiled/
|-- index.html
|-- new_user.html
|-- ssh.html
|-- editors/
|---- vim.html
|---- ed.html
|---- nano.html

wiki Command

The wiki command has 3 principles:

  1. wiki should complement, not replace, git
  2. wiki subcommands take actions that can be easily summarized in a step-by-step way
  3. wiki should be fully documented both at rest (manual page) and live (-h, usage info)

Subcommands

init
  • Clones /wiki to ~/wiki, erroring if directory exists
  • Configures .git/config accordingly
  • prints next steps
preview
  • commits working tree
  • compiles wiki
  • if it doesn't exist, creates symlink ~/public_html/wiki pointing at ~/wiki/compiled
  • prints link to ~user/wiki/
publish
  • commits working tree

  • attempts to pull from origin

    • if this fails, reports on the failure and says to fall back to git or ask for help
    • if this succeeds, pushes to origin
get <path>
  • given a valid wiki path, opens it in w3m
  • if no path, suggests creating it with $EDITOR
reset
  • prompts y/N
  • git fetch origin && git reset --hard origin

Web Presentation

A guiding principle of this RFC is that the wiki should be comfortable to view locally via w3m or similar. A CSS oriented table of content sidebar is thus out of the question. Thus, I propose the following:

  • A standalone page, toc.html, that lists the directory structure / pages of the wiki (i.e., a site map)
  • A header with a site title (The Tilde Town Wiki, for example) and basic navigation links (home, table of contents, how to contribute, tilde.town home)
  • a footer with metadata (page compile time, most recent author)
  • Source files in .txt format are turned into HTML naively; \n\n -> </p><p>.

Compiled HTML pages are put together naively: ie, it is assumed that the content of a given page can be shoved into a <body> element.

Page titling

After compiling to HTML but before combining with head.md, if the first line of a page's content is an h1 or h2 element its content will be used as the <title> of the page.

Open Questions

I'd appreciate feedback on these questions (in addition to general feedback).

  1. The compiled/ directory is ignored by git, but compiled both locally and remotely. Does this make sense? Should it not live in the folder at all?
  2. is /wiki/src/articles/ too deep of a path? is it cumbersome? i like that it is explicit and i have a policy of erring on the side of explicitness.
  3. Should the wiki command be implemented using Python's subprocess modules to call out to git or use something like PyGit2 or GitPython?

Future Improvements

  • A macro system that can handle the following expansions:

    • prefixing a string with ~: expands to a user's page link. e.g. ~vilmibm
    • prefixing a string with ~wiki: expands to a wiki page link, e.g. ~wiki:editors/ed.html
  • modify the wiki get <path> command to act as a local flavor replacement of man. This might look like a different compilation "target" distinct from compiling HTML for the web.