forked from tildetown/tilde-wiki
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