Cosma

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.

License

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.

Commands

Install

Need NodeJs v.20 or later.

You want to install app on your computer:

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

You want to install app on your own project (see exemple):

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

You have dowloaded this repository and want to execute app:

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

Development

You want build executable each time you edit files:

npm run watch:front # build web browser script
npm run watch:back # build NodeJs 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 build production app and export files with:

npm prepare
sh e2e/exec-modelize.sh

Maintenance

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

Build

The software is build as back.cjs NodeJs CommonJs executable, using Webpack. See below how 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.

Testing

Unit testing: make some asserts and documentation about business functions and models. Using 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. Using Cypress.

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

CI

For each PR and commit at "develop" branch, unit and e2e tests are executed. In case of e2e tests fail, you can download .zip contains screenshots and .html files are tested by Cypress.

Concepts

Graph

Cosma read files (.md, .csv and .json) to extract Records. Each Record contains metadatas (id, title, types, tags…) and links to other Records. Links are parsed from files content, as wikilinks [[link]] or quotes @author. Each Record became a node and links became edges on a graph. This process is made by the software named Cosmographe. Cosma finally exports .html file, which is visualization tool for the graph. This file is called Cosmoscope.

User give .yml config file contains options to control Records extraction and Cosmoscope display. For exemple, config file contains types for records and links. Cosma will remove unknows types from graph entities.