first pass on RFC
nathaniel smith
parent
1f42a5b7ec
commit
a7a3ddccec
|
|
@ -0,0 +1,137 @@
|
||||||
|
* tilde-wiki RFC
|
||||||
|
|
||||||
|
Author: [[https://tilde.town/~vilmibm][~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
|
||||||
|
|
||||||
|
#+BEGIN_EXAMPLE
|
||||||
|
/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
|
||||||
|
#+END_EXAMPLE
|
||||||
|
|
||||||
|
** 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.
|
||||||
Loading…
Reference in New Issue