User Manual for hackersphere.space

Return to capsulewide main page

This guide is for users on hackersphere.space who are already familiar with Unix and the command line. If that isn't you, read willowf's "Introduction To Unix" (work in progress):

/~willowf/unix/index.gmi

I don't have an account, but I would like one

Rules

You can email the sysadmin to request an account. This is subject to some strictly enforced rules and preconditions:

Users are not allowed to host illegal content. Illegal content will be removed as quickly as possible. This rule allows us to stay online.
Users are expected not to disrupt the other users' experience. You may login with ssh, which comes with the responsibility to treat other users and their files with respect. If you find a security vulnerability, please report it to the sysadmin. This rule allows us to remain a *public access* server.
We will not tolerate bigotry on this server. This includes racism, sexism, homophobia, transphobia, ableism, and other bigoted views of marginalized identities. Ironic humor will be considered on a case-by-case basis, but please use tone indicators where appropriate, and don't use racial or ethnic slurs. For moderation purposes, text written without tone indicators will be regarded as literal and sincere. This rule allows us to be a welcoming community and a reputable domain.

Okay, I read the rules

Find the sysadmin's contact info here:

/~willowf/contact.gmi

I have an account and I would like to know how to create content

Your user account's home directory will be a subdirectory of gemini-static/, the name of which will consist of a tilde followed by your username. You can create content by simply editing files in that directory. Any text in a *.gmi file will be treated as Gemtext, and will be available to any visitors browsing our capsule.

How do you write Gemtext?

Refer to this page:

gemini://gemini.circumlunar.space/docs/gemtext.gmi

Create your home page

Create a file in your home directory, with a name like "index.gmi" or "homepage.gmi" or something, and put whatever you like in it. Inform the sysadmin about that file to have it linked on the main page, so that visitors to the capsule can find it easily. Sample home page:

# Home page for fred's subcapsule on hackersphere.space!
Hello, my username is fred, and I sure am glad to be an account holder
=> https://github.com/fred Check out my GitHub page

Create more pages

Create more pages by creating more *.gmi files. Link them to each other to make them discoverable to capsule visitors. For example, if user "fred" has a page in their home directory called "awesome.gmi", they can link to it on any other page in the capsule with

=> /~fred/awesome.gmi

If fred has a subdirectory called "about" with a page called "contact.gmi", they can link to it with

=> /~fred/about/contact.gmi

Make a substitution rule

This capsule supports basic templating via a feature called "substitution rules" or "subrules". A substitution rule is a file named "subrule.json" which resides in your home directory or a subdirectory thereof. A subrule file defines some simple text replacements, using the following JSON structure:

{
  "@@VARIABLE@@": "replacement text"
}

With the example subrule file given above, files in the same directory will be served to the client with all instances of the string "@@VARIABLE@@" replaced with "replacement text". Template variables must all start with @@, end with @@, and contain only dashes and uppercase letters in between.

So if fred has a substitution rule that looks like this:

{
  "@@NAME@@": "fred",
  "@@PRONOUNS@@": "he/they"
}

and a page with these contents:

# @@NAME@@'s page
Hi, my name is @@NAME@@ and my pronouns are @@PRONOUNS@@.

then anyone visiting that page in a Gemini browser will receive this:

# fred's page
Hi, my name is fred and my pronouns are he/they.

and anyone viewing the page in a Web browser will see that too, except converted from Gemtext to HTML.

If a directory does not contain a substitution rule, no substitutions will be applied to the files in that directory. A substitution rule only affects the directory in which it resides and doesn't affect any subdirectories thereof.

Additionally, your substitution rule can be used to make specific content only available on Gemini. Suppose fred has a page `example.gmi` in his home directory, and he doesn't want people to be able to access that page on the Web. So he would want to add this to his substitution rule:

{
  "@@NAME@@": "fred",
  "@@PRONOUNS@@": "he/they",
  "gatekeep": [
    "/~fred/example.gmi"
  ]
}

Note that this would not work:

{
  "@@NAME@@": "fred",
  "@@PRONOUNS@@": "he/they",
  "gatekeep": [
    "example.gmi"
  ]
}

Why would I want to use a substitution rule?

The envisioned primary use case for substitution rules is to facilitate putting page headers and links on your pages, allowing you to quickly and easily update arbitrarily many pages at once by simply changing what a specific variable expands to in a substitution rule. For example, if fred wants all of their pages to contain links to their home page and contact page, they could put this in their substitution rule:

{
  "@@COMMON-LINKS@@": "=> /~fred/home-page.gmi\n=> /~fred/about/contact.gmi"
}

And then they could put this in any of their files:

@@COMMON-LINKS@@

and have it served to visitors replaced with this:

=> /~fred/home-page.gmi
=> /~fred/about/contact.gmi

and then, if they have @@COMMON-LINKS@@ on a bunch of different pages, and they want to change the links, then they just have to update their subrule.json, instead of having to manually update all of the pages one-by-one.

Automate the process

There's no reason you should have to write everything by hand with a text editor. You are free and encouraged to write programs for automating the creation and management of content on your subcapsule. For example, if you want every new page to be linked on your home page without having to write the links yourself, you could write a script that creates a new file for you and appends a link to it to your home page's file. You could even write a program that uses a Markov chain to generate posts for you, I don't care, go nuts. Just don't slow down or crash the server, don't waste a lot of disk space (ideally try to keep things under 500MB), and don't mess with files that aren't yours.

Many interpreters and compilers are available for anyone on the server to use, and more can be installed by the sysadmin on request.