tilde-wiki/rfc.org

149 lines
5.7 KiB
Org Mode
Raw Normal View History

2017-08-28 23:51:27 +00:00
* tilde-wiki RFC
2017-08-29 00:03:37 +00:00
| Author | [[https://tilde.town/~vilmibm][~vilmibm]] |
2017-08-29 06:23:31 +00:00
| Status | accepted |
2017-08-29 00:03:37 +00:00
| Date Submitted | <2017-08-28 Mon> |
2017-08-28 23:51:27 +00:00
** 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.
2017-08-29 00:22:42 +00:00
- ~wiki~: the ~wiki~ command, used locally to work on the wiki and publish changes
2017-08-29 06:23:31 +00:00
- ~tildetown/wiki~: a github repo for storing the content of our wiki
- ~tildetown/tilde-wiki~: a github repo for storing the ~wiki~ command
2017-08-28 23:51:27 +00:00
** 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
** Wiki Layout
The following is the proposed layout for the wiki with sample files
#+BEGIN_EXAMPLE
/wiki
|- .git/
|- .gitignore
2017-08-29 06:23:31 +00:00
|- wiki-githooks
2017-08-28 23:51:27 +00:00
|- src/
|-- toc.md
|-- header.md
|-- footer.md
|-- articles/
|---- index.md
|---- new_user.md
|---- ssh.html
|---- editors/
|------ vim.md
|------ ed.txt
|------ nano.html
#+END_EXAMPLE
2017-08-29 06:23:31 +00:00
After a ~wiki publish~, the resulting site structure will look like this:
#+BEGIN_EXAMPLE
/var/www/tilde.town/html/wiki/
|- index.html
|- new_user.html
|- ssh.html
|- editors/
|-- ed.html
|-- nano.html
|-- vim.html
#+END_EXAMPLE
2017-08-28 23:51:27 +00:00
** wiki Command
2017-08-29 00:03:37 +00:00
The ~wiki~ command has 4 principles:
2017-08-28 23:51:27 +00:00
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)
2017-08-29 00:03:37 +00:00
4. as needed, ~wiki~ should print human readable and informative errors.
2017-08-28 23:51:27 +00:00
*** Subcommands
**** init
- Clones /wiki to ~/wiki, erroring if directory exists
- Configures .git/config accordingly
- prints next steps
**** preview
- commits working tree
2017-08-29 06:23:31 +00:00
- compiles wiki to ~/~/public_html/wiki~
- prints link to https://tilde.town/~user/wiki/
2017-08-28 23:51:27 +00:00
**** 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
2017-08-29 06:23:31 +00:00
- compiles all source files and outputs to ~/var/www/tilde.town/wiki~
2017-08-28 23:51:27 +00:00
**** 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~
2017-08-29 06:23:31 +00:00
NB: preview and publish both audit all links in changed files for absolute
links to the wiki and error, explaining relative links.
2017-08-28 23:51:27 +00:00
** 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.
2017-08-29 06:23:31 +00:00
Does this make sense? Should it not live in the folder at all?
- After discussing with \~datagrok, I've decided to target directories outside the repo for compilation.
3. is ~/wiki/src/articles/~ too deep of a path? is it cumbersome? i like that it is
2017-08-28 23:51:27 +00:00
explicit and i have a policy of erring on the side of explicitness.
2017-08-29 06:23:31 +00:00
4. Should the ~wiki~ command be implemented using Python's ~subprocess~ modules to call
2017-08-28 23:51:27 +00:00
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.
2017-08-29 04:58:10 +00:00
- An ~admin~ subcommand with subsubcommands that can start a tilde-style wiki
at an arbitrary path. For now, the initial seeding of ~/wiki~ is all manual.