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 provides an interface to navigate and share non-linear documentation:

• if you have a personal wiki, Zettelkasten or digital garden;
• if you create mind maps, networks of people and concepts;
• if you work with citations and bibliographies;
• if you study things that involve time metadata;

then you can use Cosma to create a portable knowledge base, combining rich hypertextual descriptions with the affordances of a graph view, contextualized backlinks, automatically generated citations, metadata filters and more.

Visit https://cosma.arthurperret.fr to learn more about the software.

• Installing
• Getting started
• User manual

Cosma's development is publicly funded through Université Jean Moulin Lyon 3 and Université Bordeaux Montaigne.

This work is dual-licensed under GPL 3.0 and CeCILL 2.1. You can choose between one of them if you use this work.

Requires Node.js v22 or later.

You want to install Cosma on your computer:

npm i @graphlab-fr/cosma --global
cosma --help # enjoy

You want to install Cosma as a dependency in your own Node.js project (see exemple):

npm i @graphlab-fr/cosma
npx cosma --help
# or
./node_modules/.bin/cosma cosma --help

You have downloaded this repository and want to execute Cosma from here:

npm i # install dependences + build executable file
node dist/back.cjs # execute app

You want to rebuild the executable automatically each time you edit the source code files:

npm run watch:front # build web browser script
npm run watch:back # build Node.js executable file

# install nodemon and export files when executable change
nodemon --ext css,njk,js,cjs --watch dist/ --watch static/ --exec "sh e2e/exec-modelize.sh"

You want to build the app for production as well as test files:

npm prepare
sh e2e/exec-modelize.sh

The software is written in JavaScript. Uses ESM. Code is documented wherever possible using JSDoc, by adding headers to functions, classes and variables. You find many examples on repository. Code from the core/frontend directory should be executed in a web browser, the rest with Node.js.

The software is built as back.cjs, a Node.js CommonJS executable file, using Webpack. See below how the code is bundled in two steps.

                                      ────────────┐             
                            static/icons/**       │             
                    ───┐    static/template/**.njk│             
    core/frontend/**.js├──► front.raw.js          │             
───────────────────────┘                          │             
webpack-front.config.mjs    core/i18n.yml         │             
                            app.js                ├───► back.cjs
                            ──────────────────────┘             
                            webpack-back.config.mjs             

Read architecture.md for details about repository files and directories.

Unit testing: make some asserts and documentation about business functions and models. Uses Jest.

npm run test:unit
npm run test:unit -- --verbose --watchAll
npm run test:unit -- --runTestsByPath <filepath> --verbose --watchAll

E2E testing: generate Cosma's .html and .md files and make some asserts on. Uses Cypress.

npm prepare
sh e2e/exec-modelize.sh
npm run test:e2e -- --spec "**/graph.cy.js"

For each PR and commit on the "develop" branch, unit and e2e tests are executed. In case the e2e tests fail, you can download a .zip file containing screenshots and .html files tested by Cypress.

Cosma reads files (.md, .csv and .json) to extract Records. Each Record contains metadata (id, title, types, tags…) and links to other Records. Links are parsed from files content, as wikilinks [[link]] or citations @author. Each Record becomes a node and links become edges in a graph. This process is made by a part of the software nicknamed the Cosmographer. Cosma then exports an .html file, which is the actual visualization tool for the graph. This file is called a Cosmoscope.

Users give an .yml config file containing options to control Records extraction and Cosmoscope display. For example, config file contain types for records and links. Cosma will remove unknown types from graph entities.