Contribute to Plain Plain Text

Plain Plain Text is, hopefully, a massively collaborative project, so this page aims to show somewhat experienced users how to contribute by revealing how the modules are built, etc. But the easiest thing to do is to read our contributor code of conduct and create a pull request.

Structure of the site

If you look at the repository for this site, you can see that it’s a Jekyll site, with three collections of particular interest to contributors:

Filenames should be lowercase and with hyphens instead of spaces. Definitions, tutorials, and modules should all be writeable using only Markdown.

Style

Metadata

Every page should have a title: defined and an author: defined. The author value should be the author’s GitHub username. If the document is collaborative, then an authors: metadata array can be used, instead.

For a description file (a “whatis”), it can leverage two more pieces of metadata: official-site: is the official website (minus the http://) for an object, like atom.io, and wikipedia-title: is the Wikipedia article title for an object, like Atom (text editor). These generate the blue buttons one sees on a description card.

At this time, no other metadata is used.

Modules

<h4> headers are turned into the green buttons that open modules, and the appropriate module is indicated via the module property in the <h4> tag. More concretely, Markdown code like this:

1
2
{:module="install/atom"}
#### Install Atom

is converted into <h4 module="install/atom">Install Atom</h4>, which the site’s JavaScript subsequently turns into a green button and hidden card holding the _modules/install/atom.md module that appears when the button is clicked.

Descriptions

The JavaScript looks for links to urls that begin with /whatis/ and converts those links into links that open description cards. For example, again, Markdown code like this:

1
[atom](/whatis/atom)

is converted into <a href="#">Atom<sup><i class="fas fa-question-circle"></sup</a>, with a lot of Bootstrap-specific code suppressed, in addition to the hidden card with the description it it that appears when you click on the link.

Descriptions should be kept short, with longer exposition saved for an install module or something similar. They should be unobtrusive.

Mac/Windows toggler

Simply, the JavaScript looks for entities with the class .pc and adds the toggler inside. Then, the OSX-specific code is in an entity with the class .mac, and the Windows-specific code in one with the class .win. As such, something like this:

1
2
3
4
5
6
7
8
<div id="parentDiv" class="pc">
  <div class="mac">
    <!-- Mac content -->
  </div>
  <div class="win">
    <!-- Windows content -->
  </div>
</div>

adds the icon toggler at the top of #parentDiv and then hides whichever <div> as needed. This is also possible to achieve in Markdown, but it requires a bit of clunky code:

1
2
3
4
5
{:.pc}
The **Command Palette** is a small box in Atom that lets you search for
command names and then execute them. Launch it by typing
<kbd><kbd>cmd</kbd> <kbd>shift</kbd> <kbd>p</kbd></kbd>{:.mac}
<kbd><kbd>ctrl</kbd> <kbd>shift</kbd> <kbd>p</kbd></kbd>{:.win}.

This adds .pc to the enclosing <p> for the whole paragraph, including the <kbd> tags inside it, and .mac and .win to the appropriate parent <kbd> tags.