how to contribute to this wiki

authors:

~benharri

~audiodude

~xwindows


table of contents

Want to contribute to this wiki? §

There are at least 5 ways to contribute to this wiki:

The super ultra easy way §

To submit a new article, send an email to ~xwindows, xwindows AT tilde.club. Put the proposed contents in the email in Pandoc Markdown format. You don’t have to worry about “frontmatter”, just indicate who the author is (your tilde username), what the title of the article should be, and what category, if any, it should fall under.

~xwindows will add the article to the git repo, add the YAML frontmatter, and submit the patch for you. He’ll also email you back when the content is live on the server so you can show all your friends!

The super ultra mega easy way §

Same as the “super ultra easy way” above, except you don’t even have to add Markdown formatting if you don’t want. Just send an email with your wiki article, and all the “metadata” aka author, title, and category, and ~xwindows will add the Pandoc Markdown formatting for you (in addition to all the things from the super ultra easy way).

The easy-ish way §

This wiki exists as a git repo on Github. Whenever someone pushes a commit to the wiki directory, the wiki site gets automatically built and made live on tilde.club.

What that means is that if you can simply create a file in that repo, you will have made your article live on the wiki. But luckily, you can do that from the Github GUI! Here are some steps that might help with that.

  1. Visit the source directory of the wiki, where all the articles live. Sign in to Github.
  2. Click the “Create new file” button: screenshot of github repo
  3. Type in the file name of your article (‘my_cat.md’ for example, if the article is about your cat). Then add some YAML frontmatter with the title, author (your tilde screenname) and category, like in this screenshot: screenshot of article creation
  4. Your article contents go on the next line after the last --- of the front matter. You can write anything you want, especially using Pandoc Markdown and even HTML!
  5. When you created the file, if you didn’t have write access to the tildeclub site repository, Github had already created a personal “fork” of the repo for you. Click the “Propose new file” button when you’re done editing.
  6. You’ll go to the “Comparing changes” page, where you can review your article. Next, click “Create pull request”. Then on the next page, you can write a description of your article for the owners of the repo to see (but this will only appear on Github!)
  7. When you’re done, click “Create pull request” again. Now you will go to a page which is tracking your change to the wiki and it’s status, whether it’s been “merged” aka pulled into the wiki, and any comments that have been left.
  8. Your work is done, just sit back and wait for your change to be live on the site!

The easy way §

Maybe you found a typo on one of the existing pages, or would like to otherwise edit an article on the wiki.

You can do this right from the Github GUI!

(You might want to read the information on “The easy-ish way” for how the wiki is organized and what it means to commit to the repo)

  1. Visit the source directory of the wiki, where all the articles live. Sign in to Github.
  2. Find the markdown file of the article you want to edit. It might be similar, but not the same, as the article’s title. An easy way to find the article is to look in your browser address bar when you’re on the article’s page. The part after /wiki/ is the article name, except in Github it has an .md extension instead of .html. For example, this file is wiki.md.
  3. Click the “edit pencil” on the gray banner: screenshot of github article edit button
  4. Edit the contents of the file using Pandoc Markdown. If you don’t know what that is or don’t care, no problem! For simple grammatical and wording/phrasing fixes, you should be fine to just do them in place.
  5. Follow the steps from (5) above (the easy-ish way), except instead of clicking “Propose new file”, click “Propose file change”.

The maybe-kinda easy way §

  1. Grab a copy of the site’s source code

    git clone https://github.com/tildeclub/site tilde.club && cd tilde.club/wiki

  2. Make a new article or update an existing one. Make sure that you create the title, author, and category keys in the yaml frontmatter (see an existing article for an example).

  3. submit the code via a PR on github or with git-send-email(1) to root@tilde.club see git-send-email.io for more info on how to use it. if you’re working locally on tilde.club, you won’t have to configure anything; git will use the system’s sendmail to handle the email.

Most importantly §

Ask on irc if you have questions!

Notes for the nerds §

Following is technical information about Tilde.club website code repository (which contains Tilde.club wiki), for any of you who won’t settle for an easy way out, but would rather embark on a do-it-yourself journey of technological liberation…

  • The code of Tilde.club website (which includes the wiki) is maintained using Git version control system.

  • The master Git repository is available inside Tilde.club at /usr/share/nginx/html directory, with read-only access to Tilde.club members. In case you prefer to work on your edits directly inside Tilde.club, run a command like this to clone the repository:

    git clone /usr/share/nginx/html tildeclub-site

    If you prefer to clone to your local machine via SSH instead, use one of the following commands:

    git clone ssh://USERNAME@tilde.club/usr/share/nginx/html tildeclub-site
git clone USERNAME@tilde.club:/usr/share/nginx/html tildeclub-site
    • Don’t forget to substitute USERNAME with your Tilde.club username (else SSH would fail logging you in for the access).
    • The first command works even with a very old Git version.

    Note that you cannot issue git push from a repository cloned these ways (but git pull will work like usual), so it would be suitable mainly for email-based patch submission, or your private experiment/exploration.

  • This Git repository is also officially available online at two places:

    • GitHub (requires JavaScript and latest browser to view)
    • Tildegit (read-only mirror, replicates from GitHub; do not need JavaScript to view)

    The git clone command also work directly with these URLs; although note that pull requests are accepted only on GitHub. If you prefer not to use GitHub, email-based patch submission is also accepted.

  • Traditional email-based patch submission is accepted on email address root at tilde.club. If your patches require a use of --scissors option on git am command, please explicitly mention that on each patch email.

  • The in-repository subdirectory that contains the actual wiki text is wiki/source/.

  • Wiki articles are stored in that directory as individual files: one file per article, in Pandoc Markdown format with YAML metadata frontmatter at the top, bearing file extension .md.

  • The actual mechanism used for rendering each Markdown files into actual HTML pages on Tilde.club’s website (and text files on Tilde.club’s Gopher site) is specified in wiki/Makefile in the repository.

    • The Gophermap of the wiki is generated dynamically on Gopher request however; see wiki/gophermap and wiki/txtlist.sh in the repository for this part.

  • The copyright license of this repository is GNU General Public License, any version published by the Free Software Foundation; as stated in LICENSE file on the repository, while the any version part comes from the fallback condition specified in the section 14 of that license. If you submit your work to be a part of this wiki, this is the copyright license that your work would get published under.

    Do not trust what GitHub says about the specifics of licensing on this repository (or any other repository hosted there for that matter), always check the README, LICENSE, and COPYING files for the fine prints.