Description
Cosma is a visualization tool for knowledge workers. It reads plain text files with [[wiki links]] and renders them as an interactive network of index cards.
Cosma works with configuration files written in YAML. Each configuration file specifies a data source to be used, as well as various parameters that govern the behavior of Cosma for this data source.
Two approaches can be taken regarding configuration files:
The first approach is to run cosma in a directory where a configuration file is located. This is called a local configuration file. Local configuration files must always be named config.yml.
The other approach is to run cosma with the --project <name> option, where <name> is the name of a configuration file found in a special folder, the user data directory. This is called a global configuration file, or project. This file can be named freely (e.g. foo.yml). With this second approach, the cosma command can be run from any location.
The local approach is useful for automation and reproducibility in a context of shared or distributed work on several machines. It allows the simultaneous transmission of data, configuration and operating instructions (commands), bundled and useable as is, without any additional parameterization required from the recipient (human or machine).
Conversely, the global approach is useful for prolonged use of the software by an individual on a single machine.
Creating content: text files (Markdown)
When the data source is set on directory (Markdown file directory), the data must comply with the following rules:
- content is written in Markdown, file extension is
.md;
- metadata is expressed in YAML, in a header at the beginning of the file;
- internal links are expressed with a wiki-like syntax (double brackets
[[ ]]) and based on unique identifiers.
The following subsections explain these rules in detail.
This combination of writing standards combines several textual cultures: documentation (enriching and indexing content with metadata); wikis (interrelating documents); index cards, Zettelkasten (organising one’s notes); academic writing with Pandoc (using plain text as a source for exporting in various formats).
Therefore, Cosma works particularly well when used in tandem with writing environments that also adopt this approach, such as Zettlr or the Foam extension for Visual Studio Code and VSCodium.
Content
Cosma interprets files as being written in CommonMark, a strictly defined version of Markdown, a popular lightweight markup language.
Cosma renders Markdown files into HTML. Therefore, Markdown files can also include HTML code. Cosma also supports adding attributes by brackets, as shown below.
<div class="red">This paragraph will be red</div>
This paragraph will be red{.red}
Bitmap images can also be rendered using the Markdown syntax. Example:
To reduce the size of the cosmoscope, use images hosted on the web and included via a URL. Example:
Links
Within a record, you link to another record by writing its identifier between double brackets.
Example:
A link to [[20201209111625]] record B.
From v2 onwards, you can also include link text within the brackets.
Example:
A link to [[20201209111625|record B]]
Cosma allows you to define link types. Each link type is defined by a name, a colour and a stroke pattern. To apply a type to a link, add the name of the type followed by a colon before the identifier.
Example:
Concept B is derived from [[generic:20201209111625]] concept A.
Person D wrote against [[opponent:20201209111625]] person C.
If you do not use the alternative syntax, you can still improve the readability of records in the cosmoscope by using the link_symbol parameter. It accepts as value an arbitrary Unicode string, which will replace the identifier and square brackets in the HTML rendering of the records. This visually lightens the text by replacing numeric identifiers with a shorter, personal convention. This can be, for example, a single symbol such as a manicle ☞, an arrow →, a star ⟡, etc.
Unique identifiers
To be correctly interpreted by Cosma, each record must have a unique identifier. This identifier serves as a target for links between records.
The identifier must be a unique string.
By default, Cosma generates 14-digit identifiers in the form of a timestamp (year, month, day, hours, minutes and seconds). This is inspired by Zettelkasten note-taking applications such as The Archive and Zettlr.
We plan to eventually allow the user to define an identifier pattern of their choice, like in Zettlr.
Many interrelated note-taking applications use file names as targets for links between files. They maintain links automatically when file names are changed. By choosing to use unique identifiers instead, we have designed Cosma with a more traditional, stricter, WWW-like approach. We believe this is the easiest way to avoid link rot in a sustainable way. Avoiding the reliance on automatic link maintenance is especially important if you wish to make your data less dependent on specific applications.
Creating records with Cosma
Cosma includes several commands that allow you to quickly create records with automatically generated YAML headers.
These commands only work when select_origin is set to directory (i.e. for Markdown files).
Creating files requires a configuration file with files_origin set to a valid path. This can either be a config.yml file in the current working directory, or a project indicated by adding the -p/--projects option.
autorecord : create a record (“one-liner” mode)
cosma autorecord <title> <type> <keywords>
cosma a <title> <type> <keywords>
cosma autorecord <title> <type> <keywords> --project <name>
This command allows you to create a record with a single input. Only the title is required. If you enter multiple types or multiple keywords, separate them with commas (spaces after the comma are ignored). Example: type A, type B, keyword1, keyword2.
batch : create a batch of records
cosma batch <path>
cosma b <path>
cosma batch <path> --project <name>
This command allows you to create several records at once. <path> corresponds to the location of a file in JSON or CSV format describing the records to be created. As with all other record creation modes, the title is mandatory and the other fields are optional.
Example of a JSON file containing two records:
[
{
"title": "Title of the record"
},
{
"title": "Paul Otlet",
"type": ["Person", "History"],
"metas": {
"first name" : "Paul",
"family name": "Otlet"
},
"tags": ["documentation"],
"begin" : "1868",
"end" : "1944",
"content": "Lorem...",
"thumbnail" : "image.jpg",
"references" : ["otlet1934"]
}
]
Example of a CSV file containing these same records:
title,content,type:nature,type:field,meta:firstname,meta:lastname,tag:gender,time:begin,time:end,thumbnail,references
Title of the file,,,,,,,,,,,
Paul Otlet,Lorem...,Person,History,Paul,Otlet,man,1868,1944,image.png,otlet1934
Batch record creation and identifiers
Cosma generates 14-digit identifiers in the form of a timestamp (year, month, day, hours, minutes and seconds). This means you can manually create one record per second, or 86,400 records per day. Another way to phrase it is to say there is a range of 86,400 identifiers reserved for manual record creation each day. For example, on 15 January 2022, these identifiers range from 20220115000000 to 20220115235959.
To prevent generating duplicate identifiers, the batch creation mode generates identifiers by pseudo-timestamp. The first 8 digits, corresponding to the date (year, month, day), are real. Example: 20220115 (15 January 2022). On the other hand, those corresponding to the hours, minutes and seconds are false, generated outside of real time ranges. Example: 256495. As it is impossible to create a record manually at 25h 64min and 95s, there is no risk of generating duplicate identifiers by using both methods simultaneously.
Because of this operation, it is possible to create up to 913,599 records per day and per directory in batch mode before running out of identifiers.
Creating content: tabular data (CSV)
Cosma can interpret tabular data contained in local or online CSV files. This is an alternative to using Markdown files.
Tabular data for Cosma must be contained in two files: one for nodes and one for links. The locations of these files must be specified in the configuration file.
You can generate CSV files with a spreadsheet program. In fact, it is precisely because online collaborative spreadsheet programs such as Google Sheets exist that we have added CSV support to Cosma: they provide a cheap and efficient way to set up collective knowledge work.
We offer a Google Sheets template for you to use as a guide. One sheet should be dedicated to nodes and another to links. Click on File › Share › Publish to Web. Select the sheet containing the nodes, then change the format from “Web Page” to “Comma Separated Values (.csv)”. Click “Publish” and copy the share link. Repeat the operation for the sheet containing the links (in our template, this is the “Extraction” sheet and not the “Links” sheet). Paste each link in the corresponding field of the project configuration.
The column headers of the CSV files must comply with the following rules.
modelize: creating a cosmoscope
cosma modelize
cosma m
cosma modelize --citeproc --custom-css
Generating a sample cosmoscope
cosma modelize --sample
This command generates a sample cosmoscope. This does not require a configuration file. The cosmoscope contains an excerpt from the Cosma user manual in hypertextual form.
Applying custom CSS
cosma modelize --custom-css
It is possible to customize the appearance of a cosmoscope via CSS. To do this, set the css_custom parameter from the configuration file to the path of a CSS stylesheet, then add the --custom-css flag when generating the cosmoscope.
In order to know which selectors to use for which CSS declaration, open the cosmoscope in a web browser and use the browser’s development tools to inspect the code, or consult Cosma’s source code, specifically /cosma-core/template.njk (for the cosmoscope’s HTML structure), /cosma-core/styles.css and /cosma-core/print.css (for the print styles enabled when printing a form).
The cosmoscope stylesheets use CSS variables to define the colors and fonts used. You can redefine these variables to change all the interface elements to which they apply. In the example below, the custom.css file contains declarations that change the fonts used in the cosmoscope:
:root {
--sans: "IBM Plex Sans", sans-serif;
--serif: "IBM Plex Serif", serif;
--mono: "IBM Plex Mono", monospace;
--condensed: 'Avenir Next Condensed', sans-serif;
}
Using a global configuration file
cosma modelize --project <name>
cosma m -p <name>
The -p/--project option applies the parameters of the name project.
Excluding records from the cosmoscope
It is possible to exclude certain records from being included in the cosmoscope based on the record_filters parameter. The value of this parameter must be a list whose elements can be types, keywords or specific values of user-defined metadata (declared in record_metas). Records whose header contains at least one element of the list are excluded when generating the cosmoscope.
record_filters:
- meta: <type/tag/name of a user-defined metadata>
value: <value of type/tag/metadata>
For each filter, the meta parameter takes as its value either type (record type), tag (keyword), or the name of a used-defined metadata (declared in record_metas). The value parameter takes as value the type, keyword or metadata value for which to exclude records.
Here is an example. Consider the following record:
---
title: Paul Otlet
type: person
group: authors
tags: [documentation, pacifism]
---
Paul Otlet (1868-1944) was a Belgian lawyer, bibliographer
and pacifist who is considered the founder of
modern documentation...
The group metadata can be declared via record_metas in the configuration file:
record_metas: [group]
This allows you to use the group metadata (in addition to the title and keywords) as a criterion for excluding certain records via record_filters. In the example below, all records containing group: authors and/or the keyword pacifism are excluded:
record_filters:
- meta: group
value: authors
- meta: tag
value: pacifism
History
By default, Cosma automatically copies each generated cosmoscope to a history directory. This can be disabled by setting history: false in the configuration file.
Errors and warnings
If Cosma encounters problems during the generation of a cosmoscope, it creates an error report in a reports subdirectory of the user data directory. If the latter does not exist, reports is placed in the Cosma installation directory.
Using the cosmoscope
Layout
The cosmoscope is organised in three columns:
- Left side panel (Menu)
-
Displays exploratory features such as the index, search bar, filters, views and graph settings.
- Central area (Graph)
-
Displays the graph and associated controls (zoom, focus).
- Right side panel (Record)
-
Displays the records with a list of outgoing links (Links) and incoming links (Backlinks).
Graph
The central area of the cosmoscope is an interactive graph of labelled nodes. Each node corresponds to a record; the label corresponds to the title of the record. The links correspond to the links established between the records via their identifiers.
Hovering over a node temporarily highlights it and its connections. Clicking on a node highlights it and its connections and opens the corresponding record.
You can zoom in and out of the graph freely with a mouse or touchpad, by double-clicking on the graph background or with the dedicated buttons at the bottom left. Press C to zoom in on a selected node (whose record is open). The Reset button (shortcut: R) resets the zoom.
Nodes are organised in space by a force simulation algorithm. A coloured bar at the top of the Menu indicates the state of the drawing process (active or finished). Click on this bar (shortcut: Space) to start an additional simulation cycle. This does not reset the graph but re-runs the algorithm on the existing graph, improving its layout.
If you have a particularly tangled graph, pressing Space a few times will progressively untangle it.
The graph is not fixed: nodes can be moved by click and drag. However, the nodes and links remain permanently subject to the simulation, so it is not possible to arrange them manually. Modifying the records may change the arrangement of the nodes in space.
The way the graph is displayed can be changed temporarily via the controls under Graph settings in the Menu. To change the display permanently, change the default values of the corresponding settings in the configuration file.
Change the strength and maximum distance between nodes to adapt the display to your screen resolution and size. Add vertical/horizontal attraction to tighten the graph and bring isolated nodes closer to the center.
The graph can be displayed on all types of screens but is not optimised for mobile devices: touch does not give access to certain interactions such as hovering, and small screens greatly limit the usefulness of the graph.
Records
Records can be opened by clicking on a node, an index entry, a search engine suggestion, or a link in the body or footer of a record. Opening a record displays its contents in the right side panel.
In Cosma, you can go forward or backward with the Previous / Next buttons located in the left side panel. In a web browser, you can do the same via the browser’s Previous / Next functions. Opening a record adds the corresponding identifier at the end of the URL. This allows you to copy direct links to records.
Clicking on the “Close” button closes the right side panel and deselects the corresponding node in the graph.
The links in the records are clickable. In a browser, you can open these links in a new tab via a right click. The title of the link (displayed in a tooltip after 1-2 seconds of hovering) is the title of the corresponding card.
At the bottom of each record is a list of outgoing and incoming links (or backlinks). The links and backlinks are contextualised: when hovering over them, a tooltip is displayed, showing the paragraph that surrounds this link in the corresponding record.
This is one the most useful features in hypertext systems. It is famously absent from the Web. Many interrelated note-taking applications treat links as “first-class citizens”, and this includes contextualised backlinks. However, when these notes are shared on the Web, this feature is not always included, or it is only inclued in a paid plan. With Cosma, contextualised backlinks are part of the package, whether you’re the author of a cosmoscope working locally, or someone exploring a cosmoscope on the Web.
Focus mode
Activate Focus mode (shortcut: F) by ticking the “Focus” box at the bottom left of the graph. In Focus mode, only direct connections to the selected node are displayed in the interface. Focus mode only works if you have selected a record.
You can increase the maximum distance displayed in Focus mode with the slider located beneath the Focus button. The slider’s maximum value can be set through the focus_max parameter in the configuration file. A value of 1 means only the immediate connections will be displayed when in Focus mode. A value of 2 means you can extend the focus two connections of connections, and so on.
The focus level slider can be controlled with the arrow keys. You can combine shortcuts: F to activate Focus mode, then arrow keys to increase and decrease the focus level.
Search bar
The text field at the top of the Menu allows you to search record titles. It suggests a list of records whose title is closest to what you type in the search bar (using fuzzy search). Clicking on a suggestion selects the corresponding node in the graph and opens the corresponding record in the right side panel.
The available suggestions are constrained by the filters and focus mode: a record hidden by either of these features will not be accessible via the search engine. When you want to start from scratch for a new query, you can click on Reset display (shortcut: Alt + R).
Filtering by record type
The list of record types in the Menu allows you to filter the display. Deselecting a type hides the corresponding records in the graph, index and search engine suggestions. Deselecting a type while holding down the Alt key hides the records of all the other types.
For a type to appear in this list, it must be declared in the configuration file and be assigned to at least one record.
Filtering by keywords
The list of keywords located in the left side panel allows you to filter the graph. Selecting a keyword filters the graph and the index to display only the records that contain this keyword. You can activate several keywords simultaneously. To deactivate a keyword, click again on the corresponding button.
For a keyword to appear, it must have been declared in the tags (or keywords) field of the YAML header of at least one record.
Index
The alphabetical index of records in the Menu allows you to select a record from a list rather than through the graph. Clicking on a title selects the corresponding node in the graph and opens the corresponding record. The index can be sorted in ascending or descending alphabetical order.
Record type filters, keywords and Focus mode all modify the display of the index. A record hidden by either of these features will not be accessible via the search engine. You can reset all these effects by clicking on the “Reset current view” button under Views in the Menu (shortcut: Alt + R).
Views
A View is a state of the graph (selected form, active filters, focus mode, etc.) which can be accessed via a specific URL.