1.4.1 A few words on paths

When you use pwd (or echo %cd%), you see the full path of the working directory, beginning with / (on Linux and macOS) or \ (on Windows). This is an absolute path. The root of this path is the root of the file system. This is to files and directories what postal addresses are for people, or URLs for webpages. Regardless of you are in the file system, using cd followed by an absolute path will move you there.

A path that does not begin with / or \ is a relative path. The root of this path is the working directory. When you type cd Documents, Documents is a relative path. If you move to Documents and type cd Documents again, you won’t move unless there is another Documents nested in Documents.

A single dot . in a path means “here” (the working directory). Two dots .. means “one level up” (the parent directory). When you’re in Documents, using cd .. will bring you back to the parent directory (your home directory).

1.4.2 A few words on spaces

If the terminal encounters a space inside a path, it thinks the path ends. If you enter the following command:

cd Test folder

the terminal will run cd Test and send an error when it does not find a directory name Test.

To fix this, you have to escape spaces. “Escaping” means modifying a string of characters to prevent confusion on the machine’s end. You can escape spaces individually, or escape entire paths.

On Linux and macOS, add \ before a space:

cd Test\ Folder

On Windows, enclose the path in quotes:

cd "Test Folder"

2.2.1 Simplicity and lightness

Plain text can be objectively characterized as simple (low complexity) and light (low volume). From these two characteristics, some advantages already follow:

• Because it is simple, it is easy to use: simple format, simple interactions. But simple does not mean limited: plain text is very expressive. For machines, this simplicity also makes it easy to handle. In particular, it is easy to save and synchronize between different devices; it is perfect for versioning.
• Because it is light, it is efficient: all actions are faster (opening, editing, saving…). It is also portable, because it is quick to copy, saves storage space, and can be used as is on any operating system.

2.2.2 Freedom

Plain text is not proprietary: you can freely use it, distribute it, know how it works and modify it (these are the four fundamental freedoms of free software). The most widely used character encodings (see Encodings below), such as ASCII and UTF-8, are international standards adopted by the ISO and the IETF and can be used freely. This has several consequences that benefit users.

• It promotes competition between software, resulting in a great diversity of tools, which allows a greater freedom of choice.
• It increases the lifespan of data. There will always be a free and open source tool to replace a proprietary tool. This decreases the risk of being locked out of your data because the only tool that could interpret it becomes expensive or disappears.

2.2.3 Stability and reliability

ASCII has been around since the 1960s. UTF-8 since the 1990s. All things being equal, plain text is a more stable and therefore more reliable standard than the more recent proprietary alternatives. A text file created in the 1970s is as readable today as it was then; hopefully, this guide will be as readable in the 2070s as it is now.

2.2.4 Versatility

Plain text is incredibly flexible in the uses it allows. We’ve mentioned a couple examples (poetry, tables, graphics) but there are many more. Think about XML: a generic technique whose expressiveness allows for a potentially infinite number of applications. Plain text is just like that, and it also facilitates conversions between formats.

2.2.5 …Stoicism?

Derek Sivers has a page on plain text from a stoicist perspective. He suggests that we should increase our autonomy from technology, especially by favoring formats over features, and by having tools that allow us to work offline. According to him, we are willing to depend on particular software, especially because it offers specific functionalities that we consider indispensable. In reality, many needs can be met by simple but expressive and therefore versatile techniques. For example, plain text can replace Word, Evernote or Notion. Another example: more and more tools are offered as software-as-a-service (SAAS), usable only online; Sivers argues that we don’t always have an internet connection, and above all that disconnection can be desirable in certain contexts, as it favours concentration. It is therefore useful to have tools that are compatible with disconnection. Plain text fits into this logic.

2.2.6 Scientific plain text

Because of all these advantages, plain text is widely used in science. Over time, shared efforts have produced invaluable resources, including formats that provide interoperability. We’ve chosen to stay very close to standard formats within that ecosystem, so that we can maintain Cosma for as long as possible, and so that your data stays useable for as long as you need it.

Now that you’re sold (hopefully) on why we chose to design Cosma around plain text, let’s move on to the core concepts it is based on. Knowing these will help you avoid common pitfalls when using plain text.

2.6.1 Markdown

Markdown is a markup language. It is used to add semantic information to text, in a way that remains both easy to read and to write. It was originally meant has a shorthand for HTML and so it has only a handful of features: titles, emphasis, hyperlinks, blockquotes and a couple other things.

# A short Markdown example

Here are few lines of Markdown. Above is a level 1 title. Paragraphs need no markup, just empty lines between them. Emphasis can added with *asterisks*.

Check the following resources:

- The [CommonMark tutorial](https://commonmark.org/help/) will help you learn all about Markdown in 10 minutes.
- Wikipedia's [Markdown page](https://en.wikipedia.org/wiki/Markdown) will give you more information about Markdown, including its history.

Markdown is not tricky at all. Just keep your markup simple (don’t nest emphasis or lists too much) and consistent (don’t add too many spaces or newlines where they’re not needed).

Check the User manual for more info on using Markdown with Cosma.

2.6.2 YAML

YAML is a data serialization language. It is used to stored structured data.

Cosma uses YAML in two ways.

Firstly, YAML is used to add metadata at the top of a Markdown file. Let’s use our previous example to add a title, author name, keywords and language code:

---
title: A short Markdown example
author: Arthur Perret
keywords:
- markup
- plain text
lang: en-US
---

Here are few lines of Markdown. The level 1 title is gone, replaced with a YAML key-value pair.

You can write code between backticks in Markdown. For example, the metadata used to express the title in the YAML header above is `title`.

Secondly, YAML can be used to create configuration files for Cosma. In the example below, we set the data source, turn on the automatic history and define colors for a couple of categories used in our data:

data: '/Users/user/Documents/my-graph/'
history: true
record_types:
  concepts: #aa0000
  people: #e1e1e1

YAML looks easy, with its simple key: value pairs. But structure is enforced by white space, which makes it trickier than it looks, especially when you’ve just discovered plain text. Here are a few examples of common pitfalls:

• In a key: value pair, there must not be a space before the colon but there can be any amount of spaces right after.
• There cannot be tabulations at the beginning of lines. Indenting lines must be done with spaces.
• The --- delimiter is three dashes on a line, with no other characters (including spaces).
• Empty lines break lists.

YAML is a strict language: one character out of place will stop programs dead in their tracks. Since most of YAML writing rules involve invisible characters, beginners often don’t see where they made a mistake. You can use a text editor that includes the option to show invisible characters to check your YAML.

Check the User manual for more info on using YAML with Cosma for metadata and for configuration.

2.6.3 Wiki links

Cosma interprets wiki links. As the name suggests, these are used in wikis: a name between double brackets creates a link to the corresponding wiki page.

Paul Otlet is a pioneer of the French movement of [[documentation]], the founder of the [[Mundaneum]]. With [[Henri La Fontaine]], he co-created the [[Universal Decimal Classification]].

These aren’t as tricky as YAML. The question is what to put between brackets. Cosma allows either titles or identifiers, with the possibility of customizing the link text.

Say you have the following file:

---
title: Documentation
id: 123
---

The word "documentation" designates both the act of documenting and the product of this action.

To make a link to this file, you can write either:

Paul Otlet is a pioneer of [[documentation]].

or:

Paul Otlet is a pioneer of [[123|documentation]].

The second approach is more cumbersome but future-proof: even if you change the title of the file named “Documentation”, the link won’t break as long as you don’t change identifiers.

Check the User manual for more info on using wiki links with Cosma.

2.6.4 Citations

Cosma understands a limited subset of Pandoc’s citation syntax, which you can use to include references:

Otlet regarded classification very highly:

> "Classifying is the highest of intellectual operations" [@otlet1934, 379].

The syntax is rather simple. The trick is what is required for Cosma to transform the above into the following:

Otlet regarded classification very highly:

> "Classifying is the highest of intellectual operations" (Otlet 1934/2015, p. 379).

# Bibliography

Otlet, Paul (2015). Traité de documentation. Le livre sur le livre. Bruxelles: Impressions nouvelles. Originally published in 1934.

Cosma does this if you provide it with bibliographic data, styles and localization. The setup to create the bibliographic data can be a bit involved (we use Zotero with Better BibTeX) but it works reliably.

Check the User manual for more info on using citations with Cosma.

3.2.1 Setting up a local project

Choose an appropriate location in your file system and create a new directory called cosma-test (note the lowercase).

Inside cosma-test, create a directory called data and another one called export. We’ll create data for Cosma in the first one, and generate the visualization in the second one. We’ll put other useful files in cosma-test (we’ll refer to it as the root of the project).

Open a terminal and move to cosma-test. You can use pwd (or echo %cd% on Windows) to check that you are there, and ls to check that you can see your two sub-directories. If you’ve created cosma-test in the Documents subdirectory of your home directory, your terminal will probably look like this:

% cd Documents/cosma-test
% pwd
/Users/username/Documents/cosma-test
% ls
data export

3.2.2 Creating a local configuration file

Run the following command to create a new configuration file:

cosma config

Check your file explorer window or use ls in the terminal: you should now see a file named config.yml in cosma-test.

Open config.yml with your text editor. You should see about fifty lines of YAML, beginning with this:

select_origin: directory
files_origin: ''
…

These are the default settings for a new project in Cosma.

The first line tells Cosma that your data will consist of Markdown files in a directory:

select_origin: directory

The second line tells Cosma where the data is. For now, it’s blank:

files_origin: ''

Let’s edit this second line to tell Cosma where our data is going to be located. On Linux and macOS:

files_origin: ./data

On Windows:

files_origin: .\data

This is a relative path. A relative path starts at the same root as the file it’s written in. Since we’re writing in config.yml and it is located in cosma-test, the root of the path is cosma-test. To make it explicit, we use the dot . which means “here” (relatively to config.yml). Then we add the name of the data folder, with a slash / (or \ on Windows) to separate directory names.

We’re doing this because if you move the folder around, this path will still work, as it is relative to the folder itself and not where the folder is located within the file system.

Let’s tell Cosma where we want it to create the output file. On Linux and macOS:

export_target: ./export/

On Windows:

export_target: .\export\

(Note the trailing slash. Cosma needs it.)

That’s it: this is enough to start creating data.

3.2.3 Creating data

Cosma is a graph visualization tool: your data will be made of things and relationships between these things.

This abstraction is built on top of plain text files. Cosma can read two kinds of files: Markdown and CSV. In the case of Markdown, each thing is described in its own dedicated file, written in Markdown. In the case of CSV, a single file contains all the things. Here, we’re going to create Markdown files.

Let’s create our first file. We could do this manually but let’s use Cosma’s built-in command for generating Markdown files:

cosma record

When you press enter, Cosma will ask you for a title:

% cosma record
title (required):  

Type Evergreen notes then press Enter.

Cosma will then ask you for one or more types. Type concept then press Enter.

Cosma will then ask you for one or more tags. Press Enter to skip this.

You should now see a confirmation that a file called evergreen-notes.md has been created in data.

You should also see a warning about concept not being defined in the configuration. Warnings are important but they don’t stop Cosma from working. Let’s ignore it for now, we’ll come back to it later.

Open evergreen-notes.md in your text editor. You should see something like this:

---
title: Evergreen notes
id: 20230515104916
type: concept
---
 

Add another newline so there’s an empty line between the second --- delimiter and the rest of the file. This is not mandatory, it just makes it easier to separate the YAML header and the rest visually. Then copy and paste the following text at the bottom of the file:

Evergreen notes are written and organized to evolve, contribute, and accumulate over time, across projects. This is an unusual way to think about writing notes: most people take only transient notes. That’s because these practices aren’t about writing notes; they’re about effectively developing insight: “Better note-taking” misses the point; what matters is “better thinking”. When done well, these notes can be quite valuable.

(This is from Andy Matuschak’s working notes. Andy is an important contributor to the ecosystem of tools for thought. If you don’t know his work, check his website.)

The file should now look like this:

---
title: Evergreen notes
id: 20230515104916
type: concept
---

Evergreen notes are written and organized to evolve, contribute, and accumulate over time, across projects. This is an unusual way to think about writing notes: most people take only transient notes. That’s because these practices aren’t about writing notes; they’re about effectively developing insight: “Better note-taking” misses the point; what matters is “better thinking”. When done well, these notes can be quite valuable.

Let’s create a second file. Run cosma record again. Remember, since you already used this command, you can press up-arrow to find it back instead of typing it again.

When Cosma asks for a title, type Evergreen notes should be atomic.

When Cosma asks for one or more types, type insight.

When Cosma asks for one or more tags, press Enter to skip this.

You should now have another file in data, called evergreen-notes-should-be-atomic.md. Again, ignore the warnings for now.

Open evergreen-notes-should-be-atomic.md and add the following text to it:

Evergreen notes should be atomic. It’s best to create notes which are only about one thing—but which, as much as possible, capture the entirety of that thing.

The file should now look like this:

---
title: Evergreen notes should be atomic
id: 20230515105059
type: insight
---

Evergreen notes should be atomic. It’s best to create notes which are only about one thing—but which, as much as possible, capture the entirety of that thing.

Now, let’s add a link. In the file titled “Evergreen notes should be atomic”, edit the first sentence (not in the YAML header but below it) by adding double brackets around Evergreen notes. Then, inside the double brackets and before Evergreen notes, add the identifier for that record, followed by a vertical bar |. You can find the identifier for Evergreen notes in the YAML header of evergreen-notes.md, after id: .

---
title: Evergreen notes should be atomic
id: 20230515105059
type: insight
---

[[20230515104916|Evergreen notes]] should be atomic. It’s best to create notes which are only about one thing—but which, as much as possible, capture the entirety of that thing.

The id used in the link in the above example is 20230515104916. It’s probably different from the one you see in your version of evergreen-notes.md. This is normal: when creating a record, Cosma generates its 14-digit identifier by taking a timestamp (year, month, day, hour, minute, second). Just replace 20230515104916 by the id you see in your version of evergreen-notes.md.

We now have two things and a link between them: it’s a graph! Let’s visualize it.

3.2.4 Creating a cosmoscope

In your terminal, check that you’re still in cosma-test, then run the following command:

cosma modelize

Your terminal should look like this:

% cosma modelize  
[Cosma v.2.0.0]  /Users/username/Documents/cosma-test/config.yml
Building cosmoscope… (source type: directory)
Cosmoscope generated (2 records)
Report: 2 warnings
/Users/username/Library/Logs/cosma-cli/logs/20230503150704.html

We should now have a cosmoscope.html file in the export directory, but what’s this about a report and two warnings? You may have guessed it: it’s to do with those warnings Cosma gave you when you created the Markdown files.

Look at the last line of the message in your terminal. It’s a path:

/Users/username/Library/Logs/cosma-cli/logs/20230503150704.html

Locate this file and open it in your web browser. You can do this via your file explorer, or with your terminal: copy the path, then use the open command followed by the path.

open /Users/username/Library/Logs/cosma-cli/logs/20230503150704.html

You should see something like this:

Cosma - Log file - 202305031507:04
Errors (0 records)
Warnings (2 records)
Evergreen notes
- Type "concept" of "Evergreen note" unrecognized, treated as "undefined"
Evergreen notes should be atomic
- Type "insight" of "Evergreen notes should be atomic" unrecognized, treated as "undefined"

Cosma doesnt’t know about concept and insight because types have to be listed in the configuration. (We made you proceed despite the warnings on purpose, in order to show you where you can check warnings and errors.)

Addressing these warnings is easy. Open the config.yml file from cosma-test. Locate these lines:

record_types:
  undefined:
    fill: "#858585"
    stroke: "#858585"

This is the list of types. Each type is listed on a new line, with two spaces at the beginning of the line to indicate that it is a child of parameter record_types. Each type is defined by a name. Under that name are two properties, fill and stroke, which take a hexadecimal color code as their value. These colors are used in the output; they help distinguish between records of different types.

Let’s add our two types:

record_types:
  undefined:
    fill: "#858585"
    stroke: "#858585"
  concept:
    fill: "#984ea3"
    stroke: "#984ea3"
  insight:
    fill: "#ff7f00"
    stroke: "#ff7f00"

(Note that there are two or four spaces at the beginning of each line.)

Now, let’s go back to our terminal and run the cosma modelize command again. You can press the up-arrow key to call it back, then press Enter.

You should see the same message as before but without the warnings this time:

% cosma modelize  
[Cosma v.2.0.0]  /Users/username/Documents/cosma-test/config.yml
Building cosmoscope… (source type: directory)
Cosmoscope generated (2 records)

Check the cosma-test directory. You should see a history subdirectory. This is created automatically by Cosma when the configuration contains history: true. The cosmoscope.html file in export is overwritten each time you run cosma modelize. But when history: true, Cosma also saves each cosmoscope in history. This allows you to check previous versions. Be careful though: it can also eat up a fair amount of disk space.

You should have two files in cosma-test/history, one for each time you ran cosma modelize. You can open both of these files in your web browser to check the difference between them: the first one (with the warnings) doesn’t include your types; the second one does.

3.2.5 Using a cosmoscope

With your web browser, open the cosmoscope.html file located in the export subdirectory of cosma-test. Let’s take a tour of the interface.

In the middle, you see a visual representation of your files as colored nodes, with links corresponding to the wiki links between them.

Clicking on a node opens a rightside panel which displays the contents of the file. At the bottom of this panel is a list of links and backlinks. Backlinks are the links that point to the record you’re currently viewing. Hover above this backlink and Cosma shows you its context in the corresponding record. Basically, it tells you where things are mentioned and how.

Here, “Evergreen notes” has a backlink from “Evergreen notes should be atomic”. If you need to write something on evergreen notes, you can review this record and check the backlinks to remind yourself of what you’ve written about this concept. This is one of the most important features of Cosma.

On the left is a navigation panel. The search box allows you to look up titles. The index is an alphabetical list of the records. Then there are display filters: the list of types for example allows you to hide or show all records of each type. This is not very useful when you only have two records, but if you get to a few hundred records, it can help you switch between a full graph and a more focused view. At the bottom left of the graph are other filters: Focus hides records not connected to the one which is currently selected; Chronological hides or shows records based on time metadata.

You can tweak the graph layout algorithm live from within the cosmoscope. Check “Graph parameters” in the panel on the left. These are reset every time you refresh the page. If you find settings you like, you can change the corresponding parameters in the configuration file; then run cosma modelize again to create a new version of the cosmoscope with these settings.

3.3.1 Setting up for global projects

Before you can create global projects, you have to create the Cosma user data directory. You only have to do this once.

Open a terminal. If you had one open from the previous tutorial, run cd (no argument) in order to go back to your home directory. You don’t need to be in a specific location for this, it’s just to start the tutorial with a fresh context.

Run cosma with this flag:

cosma --create-user-data-dir

Cosma will confirm the creation of the user data directory and show you its path. This path varies depending on your operating system. If you ever forget this path, run the above command again: Cosma will tell you the directory already exists and show you the path again.

Cosma can create global configuration files for you in the user data directory, but doesn’t overwrite or delete them. You can use this directory to store other files. Uninstalling Cosma doesn’t remove this directory.

3.3.2 Creating a global configuration file

Run the following command to create a new global configuration file for a project called cosma-test:

cosma config -g cosma-test

Cosma will confirm the creation of cosma-test.yml and show you its path.

Open cosma-test.yml with your text editor. You should see the same fifty-odd lines of YAML as when you created the local configuration file in the previous tutorial.

Let’s tell Cosma where the data is. We’ll reuse data from our cosma-test directory but this time, we’ll point to its absolute path:

files_origin: /Users/username/Documents/cosma-test/data

Let’s do the same for the export folder:

export_target: /Users/username/Documents/cosma-test/export/

(Note the trailing slash for the export path.)

This time, let’s edit the list of types right away:

record_types:
  undefined:
    fill: "#858585"
    stroke: "#858585"
  concept:
    fill: "#984ea3"
    stroke: "#984ea3"
  insight:
    fill: "#ff7f00"
    stroke: "#ff7f00"

(You can copy paste this from the config.yml file from the previous tutorial but make sure that the indentation is correct: two spaces at the beginning of each line.)

Finally, let’s edit the title parameter. We’ll call this project “A test of Cosma”

title: 'A test of Cosma'

3.3.3 Creating data (round two)

Let’s create a couple of files. We’re going to use cosma record but this time with the --project option followed by the configuration’s name:

cosma record --project cosma-test

When Cosma asks you for the title, type Evergreen notes should be concept-oriented. Use insight for the type, and skip tags.

You’ve just created a file in cosma-test/data, without having had to move there. It did not matter where you were in the file system when you ran this command. You just had to remember the name cosma-test. This is the point of a global configuration: to be able to open a terminal and run cosma right away. Using the --project option is a bit like using a bookmark to visit a site rather than typing its URL.

Open the newly created file and add the following text. Don’t forget to replace the id accordingly.

It’s best to factor [[20230515104916|Evergreen notes]] by concept (rather than by author, book, event, project, topic, etc). This way, you discover connections across books and domains as you update and link to the note over time.

(Note the link.)

Run the same command again (press up-arrow to retrieve it, then Enter). Use Evergreen notes should be densely linked as the title, insight as the type, and skip tags.

Open the newly created file and add the following text (again, replace the id accordingly):

If we push ourselves to add lots of links between our notes, that makes us think expansively about what other concepts might be related to what we’re thinking about. It creates pressure to think carefully about how ideas relate to each other (see [[20230515110033|Evergreen notes should be concept-oriented]]). It’ll also help you internalize the ideas more deeply.

3.3.4 Creating a cosmoscope (round two)

Run the following command:

cosma modelize --project cosma-test

Your terminal should look like this:

% cosma modelize --project cosma-test  
[Cosma v.2.0.0] A test of Cosma /Users/username/Documents/cosma-test/config.yml
Building cosmoscope… (source type: directory)
Cosmoscope generated (4 records)

Note the number of records, as well as the fact that Cosma picked up on your project’s title and displayed it.

With your web browser, open the cosmoscope.html file from cosma-test/export. There should be two more records, and the title “A test of Cosma” at the top left of the interface.