* tilde-wiki RFC
| Author | [[https://tilde.town/~vilmibm][~vilmibm]] |
| Status | accepted |
| 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
- ~tildetown/wiki~: a github repo for storing the content of our wiki
- ~tildetown/tilde-wiki~: a github repo for storing the ~wiki~ command
** 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
|- wiki-githooks
|- src/
|-- toc.md
|-- header.md
|-- footer.md
|-- articles/
|---- index.md
|---- new_user.md
|---- ssh.html
|---- editors/
|------ vim.md
|------ ed.txt
|------ nano.html
#+END_EXAMPLE
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
** wiki Command
The ~wiki~ command has 4 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)
4. as needed, ~wiki~ should print human readable and informative errors.
*** Subcommands
**** init
- Clones /wiki to ~/wiki, erroring if directory exists
- Configures .git/config accordingly
- prints next steps
**** preview
- commits working tree
- compiles wiki to ~/~/public_html/wiki~
- prints link to https://tilde.town/~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
- compiles all source files and outputs to ~/var/www/tilde.town/wiki~
**** get
~. Compiled HTML pages are put together naively: ie, it is assumed that the content of a given page can be shoved into a ~
~ 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 ~