~ 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.

* 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 - 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~ -> ~

~. 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 ~~ 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.