Readme

Sidenotes

A clojure documentation generator forked from marginalia that displays code and comments side by side.

The documentation for sidenotes itself can be found here

Features

It is limited to projects that use deps.edn.

Currently the following features are supported:

Generating table of contents containing dependencies and namespaces
One html file per namespace showing code and comments side by side
Support for markdown in comments
Disabling / Enabling adding comments to the documentation with @SidenotesDisable and @SidenotesEnable inside comments
Choosing the filename for the table of contents
Support for external themes

Differences to Marginalia

Limited to projects using deps.edn
No Latex output
No uberdoc output
Javascript and CSS are not injected into html files but kept separate
Uses clostache/mustache for templating
A new theme sidenotes in addition to the classic marginalia
Inclusion of the project readme in the table of contents page if it is written in markdown
Support for external themes

Usage and Configuration

Add an alias to your deps.edn file

:sidenotes
{:extra-deps
{sidenotes/sidenotes {:mvn/version "RELEASE"}}
:main-opts  ["-m" "sidenotes.core"]}

and call it

clojure -A:sidenotes

This will create the documentation in a folder called docs. You can change this by creating a file sidenotes.edn in your project root. It can also be used to add a project name and description. The project name is otherwise read for the current folder. Other settings are available as well:

{:projectname "Sidenotes"
 :description "Clojure documentation generator"
 :output-to "docs"
 :toc-filename "index.html"
 :include-readme true
 :theme "marginalia or sidenotes"}

Setting	Description
`:projectname`	Sets the name of the project in the table of contents page
`:description`	Sets the description of the project in the table of contents page
`:output-to`	The folder the documentation will be written to, defaults to `docs`
`:toc-filename`	The filename of the table of contents page. Defaults to `toc.html`
`:include-readme`	Include the readme (if it is markdown) in the table of contents page. Available only in `sidenotes` theme
`:theme`	The theme to use. Defaults to `marginalia`
	Select `marginalia` if you want it similar to what marginalia generates
	Select `sidenotes` if you want the new css grid based layout with new features
	Or configure the path to your own theme for more flexibility in rendering the documentation

External Themes

Sidenotes is able to use your own theme in addition to the included ones.

If you'd like to create your own you need three files for it:

`toc.html`

A mustache template that renders the table of contents. It is a good idea to start with the template in the sidenotes theme to see which parameters it takes to build the table of contents.

`ns.html`

A mustache template that is used for every namespace. Again it is wise to start with the existing one.

`theme.edn`

In case your theme uses additional resources like css, JavaScript or images this file need to contain references to them, so sidenotes knows to copy them into the output folder. It should look like this:

{:resources
 ["css/sidenotes.css"
  "css/shCore.css"
  "css/shThemeSidenotes.css"
  "js/jquery-1.7.1.min.js"
  "js/xregexp-min.js"
  "js/shCore.js"
  "js/shBrushClojure.js"
  "js/app.js"
  "img/spacer.svg"
  "img/cljs-white.svg"
  "img/Clojure_logo.svg"]}

Future Work

Currently I have no features in mind that need to be added to sidenotes. If you would like to see something let me know about it or create a pull request for it.