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 either the title or identifier between double brackets.
The id field is optional. But if a record has one, trying to link to tis record based on its title field will fail, as the id takes precedence.
Example of title-based link:
A link to [[record B]].
For title-based links, text case is ignored when parsing but preserved when rendering. So you can write [[Record B]], [[record B]] or even [[rEcOrD b]]: the link will work regardless, and the text will be rendered the way you wrote it.
Example of identifier-based link:
A link to [[20201209111625]] record B.
For identifier-based links, you can also include link text within the brackets. It can be any string except ]] (the ending delimiter of the link). Example:
A link to [[20201209111625|record B]].
Cosma also allows you to define link types. Each link type must be defined in the configuration 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. The name can be any string except :, | and ]] (characters reserved for the link syntax).
Example:
Concept B is derived from [[generic:concept A]].
Person D wrote against [[opponent:20201209111626|person C]].
If you use identifier-based links without link text, perhaps coming from software such as The Archive and Zettlr, you can 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
Each record can have an optional unique identifier. If present, this identifier is used instead of the title as a target for links between records.
The identifier must be a unique string.
By default, when you create a record with cosma record, Cosma generates a 14-digit identifier 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.
For each project, you can choose to generate identifiers always, never or on a case-by-case basis by setting the generate_id parameter in the project’s configuration.
We support title-based links but encourage the use of unique identifiers instead. We believe this is the easiest way to avoid link rot in a sustainable way, avoiding the reliance on a program to automatically maintain links. This 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.
If generate_id is set to ask, use the -id/--generated-id flag to automatically generate an identifier when using autorecord.
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.
In v2.1, batch generates buggy identifiers, with extra digits (more than the expected 14). This doesn’t affect projects with generate_id: never, for which batch correctly generates records without 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.
Citations and bibliographies
Cosma includes automatic citation processing. This functionality is based on the same techniques as Zettlr: bibliographic data and styles use the Citation Style Language (CSL) standard, while the insertion of citations in the text is done with the Pandoc citation syntax.
Required files
To automatically process citations, Cosma requires three files:
- Bibliographic data
-
File containing metadata describing bibliographic references. The required format is CSL JSON (extension
.json).
- Bibliographic style
-
File containing the formatting rules for citations and bibliographies. The required format is CSL (extension
.csl). You can download style files from the Zotero CSL styles directory.
- Bibliographic localization
-
File containing localized terms used in bibliographies (e.g. “publisher”, “issue”…). The required format is XML (extension
.xml). You can download localization files from the CSL project GitHub repository.
In the data file, each reference must have a unique identifier (id) that serves as a citation key. Example:
[
{
"id":"goody1977",
"author":[{"family":"Goody","given":"Jack"}],
"citation-key":"goody1977",
"event-place":"Cambridge",
"ISBN":"978-0-521-21726-2",
"issued":{"date-parts":[[1977]]},
"language":"en",
"number-of-pages":"179",
"publisher":"Cambridge University Press",
"publisher-place":"Cambridge",
"title":"The Domestication of the Savage Mind",
"type":"book"
},
]
You can use the bibliographic reference manager Zotero with the Better BibTeX extension to create unique citation keys for each reference and have an automatically updated export of your library that Cosma can use.
Citation syntax
To cite a reference in a record, include the citation key for that reference using the Pandoc citation syntax.
Example:
On writing as a technology of the intellect [@goody1977, 46-52]...
Processing citations
cosma modelize --citeproc
When processing citations, each citation key is replaced with formatted text and a bibliography is generated below the body of each record containing references.
Example:
On writing as a technology of the intellect (Goody 1977, 46-52)…
Bibliography
------------
GOODY, Jack, 1977. The Domestication of the Savage Mind.
Cambridge University Press. ISBN 978-0-521-21726-2.
The CSL JSON data matching the cited references is embedded in the cosmoscope. You can view and download this data in the cosmoscope by clicking on the “Data” button at the bottom of the left-hand side menu. You can also access it from within the cosmoscope source code, under the <article id="citation-references"> tag.
Treating references as graph nodes
When configuration setting references_as_nodes is set to true, it modifies the behavior of the --citeproc option of cosma modelize, making it so that bibliographic references become nodes in the graph: each cited reference is treated as a node and each citation is treated as a link; for each cited reference, a bibliographic record is automatically generated in the cosmoscope; each bibliographic record is presented with contextualized backlinks which correspond to citations of that bibliographic reference in other records.
To use this feature, you must do three things:
- set
references_as_nodes to true in the project’s configuration;
- define a value for
references_type_label (this is a new setting introduced alongside references_as_nodes in this release);
- create a record type with the same name as the value for
references_type_label.
For instance:
references_as_nodes: true
references_type_label: "référence"
record_types:
référence:
stroke: "#6C6C6C"
fill: "#6C6C6C"
When references are treated as nodes, you can use link types on citations. Link types can only be used when citations are within brackets. They must be the first string within the brackets, ending with a colon :. Example:
On writing as a technology of the intellect [cites as authority:@goody1977, 46-52]...
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).
The panels can be hidden or shown by clicking on toggle buttons (respectively at the top left and top right of the cosmoscope).
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. It also centers the graph view on that node. Press C to manually center on the selected node.
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. 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.
You can go forward or backward with 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.
To deselect a node, press the Esc key.
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 record.
At the bottom of each record is a list of outgoing links (section titled “Links”) and incoming links (section titled “Backlinks”). Links and backlinks are contextualised: they are presented with the surrounding paragraph in the source record. You can set link_context to inline instead of tooltip if you want the link context to be displayed at all times, instead of in a tooltip on hover.
Contextualised backlinks are 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 included 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).
View
The view is the state of the cosmoscope at any time (selected record, active filters, focus mode, etc.). The view can be reset by clicking the “Reset the view” button in the “View” section of the left panel. The view can also be saved by clicking “Set URL to current view” then copying the URL, which can be used as a bookmark to access that view directly.