how to contribute to this wiki
benharri; audiodude; xwindows


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[1], 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[2]. 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[3] of the wiki, where all the articles
    live. Sign in to Github.
2.  Click the “Create new file” button:
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:
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[4] 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[5] 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:
4.  Edit the contents of the file using Pandoc Markdown[6]. 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[7] 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[8].

-   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[9] (requires JavaScript and latest browser to view)
    -   Tildegit[10] (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[11] with YAML
    metadata[12] 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[13], any version published by the Free Software
    Foundation[14]; 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.

[1] /~xwindows/

[2] https://github.com/tildeclub/site/tree/master/wiki/

[3] https://github.com/tildeclub/site/tree/master/wiki/source

[4] https://pandoc.org/MANUAL.html#pandocs-markdown

[5] https://github.com/tildeclub/site/tree/master/wiki/source

[6] https://pandoc.org/MANUAL.html#pandocs-markdown

[7] https://git-send-email.io

[8] https://git-scm.com

[9] https://github.com/tildeclub/site/

[10] https://tildegit.org/club/site/

[11] https://pandoc.org/MANUAL.html#pandocs-markdown

[12] https://pandoc.org/MANUAL.html#extension-yaml_metadata_block

[13] https://www.gnu.org/licenses/gpl.html

[14] https://www.fsf.org