Agitcms NPM | npm.io

/eɪdʒɪt/

Agit CMS is a simple web frontend interface for markdown-based static site generators, like Hugo and Jekyll.
Write markdown blog posts the hackable way, get rid of your itch points.

frontmatter

Install

npm install -g agitcms

To start: agitcms
To change port: AGIT_FRONTEND=3001 agitcms

Features

vertical split style markdown editor
type-aware frontmatter editor
custom editor snippet/toolbar/keymap
custom frontmatter language(yaml/toml) & delimiters
Integrated Terminal
mathjax rendering: $ a + b = c$
image pasting into the editor

Agit CMS tries to be a hackable headless CMS for developers.

Comparison with other CMS

	Agit CMS	Netlify CMS
Where CMS runs	Runs on your computer	Runs on website's /admin (which is a security issue)
Installation	easy(npm i)	hard
image pasting	O	X
mathjax rendering	O	△(requires additional setup)
Integrated Terminal	O	X
customizability	O	X

Quick Start

Adding a new site

Open Agit CMS and click NEW button.

Type your site’s name, and root folder path of the static site. These two configurations cannot be changed afterwards unless you modify ~/.agitcms/config.json directly.

Once you add a new site, click on it, then Agit CMS provides a file explorer where you can navigate through folders and files thas have .md extension.

Click PIN button at the very top to pin a folder or a file to left sidebar for easy access.

Integrated Terminal

Press Control + @ to open up a integrated terminal.

Try starting a server of your static sites generator.

In hugo: hugo server
In jekyll: jekyll server

npm.io

Now your preview server is running on your host!
Try modifying a post as you wish, with a nice markdown&frontmatter editor!

Usage

Markdown Editor

default keymaps

Visit here and here for keymaps available by default.

custom keymaps

Want to add your own keymaps?
Try creating your own plugin!

mathjax

Type

$$
a + b = c
$$

to represent block math.
Type

$$ a + b = c $$

or

$ a + b = c $

or 

$
a + b = c
$

to represent inline math.

image pasting

Agit CMS allows Ctrl + v to paste images into the editor.

This feature is useful when you want to paste a screen capture without looking for its file name.

Set media folder path and media public path to enable this feature.

A couple of things to note

Images larger than 1MB cannot be pasted.
At this version, all images pasted into the editor are saved in year-month-date-time.png format

Media

![](${media_public_path}/example.png) written in the markdown editor panel (left side) gets parsed into <img src="http://localhost:${random_port}/${media_public_path}/example.png"> in the preview panel at the right side . (${media_public_path} is a media public path)

Agit CMS starts local http server on ${random_port} at media folder path in the filesystem to serve media contents.
HTTP server automatically closes when Agit CMS is closed.

There are a couple of things to note

On Windows, you might have to tell windows to allow Agit CMS to start HTTP server when a warning is shown.
Image placed in the same folder as the markdown post file is in cannot be previewed at this version.

To quickly get the image path you want to insert into the editor, Agit CMS has a file explorer shortcut button Media for it.
It opens media folder path, and the selected image's public path will be copied into your clipboard.
This way, you can easily type ![](${ctrl + v}) (where ${ctrl + v} means pressing ctrl + v) to insert the image.

Plugins

The markdown editor of Agit CMS (Codemirror) can be customized by creating your own plugins.

Agit CMS evaluate javascript files in ~/.agitcms/plugins as plugins when boot, so you can place your own javascript file here to create a plugin. Name of the file does not matter.

Creating your own plugin requires a bit of knowledge of codemirror. If you don't know any, Examples is helpful.

There are two types of plugins.

Toolbar Item: manually invoked
TransactionFilter: automatically invoked

Toolbar Item

To create Toolbar Item plugin, create a new instance of ToolbarItem class and provide a valid config as a first argument.

If you don't want your plugin to show up in the toolbar, set config.initialChar to empty. That way you can only call the plugin via config.keyAlias

See table plugin for an exmaple.

Transaction Filter

Every time editor updates its document, this type of plugins, i.e., Transaction Filter plugin is called. Unlike ToolbarItem plugin, Transaction Filter does not modify,

To create Transaction Filter plugin, create a new instance of Transaction Filter class and provide a valid config as a first argument.

Examples

table plugin

A plugin that inserts markdown table syntax when clicked on the toolbar, or when ctrl + shift + t is pressed.

//put this in ~/.agitcms/plugins
new ToolbarItem({
  initialChar: "T",
  keyAlias: "Ctrl-T",
  run: (editorView) => {
    const from =
      editorView.state.selection.ranges[editorView.state.selection.mainIndex]
        .to;
    const insert = "|  |  |\n|---|---|\n";

    editorView.dispatch({
      changes: { from, insert },
      selection: { anchor: from + 2 }, //puts cursor to from+2
    });
  },
});

shortcode snippet plugin

This is a plugin that works as a snippet. If you are using Hugo for example, you might want to add shortcode snippets.

The plugin below inserts {{</*alert `\n\n` [info] */>}} to editor and sets cursor at position between two \n.
Also note that this plugin is activated for sites that has name "0xsuk's blog". (Name of the site is the one you set in the home)

const sitesToEnablePlugin = ["0xsuk's blog"];
new ToolbarItem({
  initialChar: "A",
  weight: 5,
  run: (editorView) => {
    const from =
      editorView.state.selection.ranges[editorView.state.selection.mainIndex]
        .to;
    const insert = "{{</*alert `\n\n` info*/>}}";

    editorView.dispatch({
      changes: { from, insert },
      selection: { anchor: from + 11 },
    });

    editorView.focus();
  },
  isActive: (siteConfig) => {
    if (sitesToEnablePlugin.includes(siteConfig.name)) {
      return true;
    }
    return false;
  },
});

autoclosebracket plugin

function handleAutoclose(transactionSpecList, transaction) {
  return function forBracket(opening, closing) {
    transaction.changes.iterChanges((fromA, _, fromB, toB) => {
      const newChars = transaction.newDoc.sliceString(fromB, toB);
      if (newChars === opening) {
        transactionSpecList.push({
          changes: { from: fromA, insert: opening + closing },
          selection: { anchor: fromA + 1 },
          filter: false, //do not filter transaction for this update to prevent unintended behaviour
        });
      }
      if (newChars === closing) {
        //if the next char is also closing bracket, move cursor right
        const nextChar = transaction.startState.sliceDoc(fromA, fromA + 1);
        if (nextChar === closing) {
          transactionSpecList.push({
            selection: { anchor: fromA + 1 },
            filter: false,
          });
        }
      }
    });
  };
}
new TransactionFilter({
  fn: (transaction) => {
    const transactionSpecList = [];
    const forBracket = handleAutoclose(transactionSpecList, transaction);
    forBracket("[", "]");
    forBracket("(", ")");

    return transactionSpecList;
  },
});

japanese keymap

new TransactionFilter({
  map: new Map([
    ["＃", "#"], //mapping japanese # to english #
    ["　", " "], //mapping japanese space to english space
  ]),
});

Integrated Terminal

Press Ctrl + @ to open/hide.
Press ctrl+d to kill a process. If a process is killed, integrated terminal automatically closes.

Click + to add an instance.

If you navigate to Home while integrated terminal is open, all instances will be inaccesible, but still be running in the background.

Global settings

Navigate to Home (start page), and click on Settings in GLOBAL section of the sidebar.

Open Integrated Terminal with Ctrl+@

Disable this to prevent Agit CMS from opening an integrated terminal when ctrl+@ is captured.

Site settings

Go to one of site you added, and click on Settings in SITE section of the sidebar.

Frontmatter language

Define what language you use to represent frontmatter in markdown posts.

Default: yaml

Frontmatter delimiters

Define what delimiters you use to wrap frontmatter.
If you want to parse frontmatter in toml like below, you want to set frontmatter delimiters to +++, and frontmatter language to toml.

+++
title = example
+++
# Heading of the article
...

Default: ---

Frontmatter template

This one is optional but recommended if you want to parse frontmatter with correct types, or if you want to create new posts by CREATE NEW button of the Agit CMS file explorer.

Frontmatter template specifies what type each property of frontmatter is attributed to.

This information is used when Agit CMS parses markdown and generates a type-aware frontmatter editor, or when Agit CMS creates a new post with default frontmatter values.

example

Let's take a frontmatter below for example.

---
title: Configuration
date: '2022-07-03T17:52:46+09:00'
draft: false
tags: ["React.js", "Web Dev"]
---

When Agit CMS parses frontmatter and generates a type-aware frontmatter editor, it tries to find a type for each property of frontmatter.

If you set date property of frontmatter to be a type of Date for instance, Agit CMS provides a date picker in the frontmatter editor.
If you set draft to be a type of Bool, Agit CMS provides a boolean toggler in the frontmatter editor.

Supported types

type
Text	plain text (ex. `title: Configuration`)
List of Text	list of text (ex. `tags: ["React.js", "Web Dev"]`)
Multiline Text	text with multiple lines
Date	date in ISO 8601 format (ex. `date: '2022-07-03T17:52:46+09:00'`)
Bool	`true` or `false` (ex. `draft: false`)
Nest	property that contains child properties

Media Folder Path

Specify where you store media (image, GIF and so on) in your file system.

Media Public Path

Specify the url path media content is accesible from.

example

Suppose media folder path is /home/mysite/static/uploads, and /home/mysite/static/uploads/example.png's url is https://mywebsite.com/contents/images/example.png.

Then media public path should be /contents/images.

API Reference

siteConfig

property	desc
name	name of the site
key	unique id
path	the root path of the site
frontmatterLanguage	frontmatter language (yaml/toml)
frontmatterDelimiter	frontmatter delimiter
media.staticPath	static path (filesystem path) of the media folder
media.publicPath	public path (url path) of the media contents
pinnedDirs	array of pinned folders and files
frontmatter	frontmatter template

class Plugin

property/method	desc	type	default
constructor({isActive})	create new instance
isActive	Plugin is active or not	bool \| (siteConfig) => bool	true

class ToolbarItem

subclass of Plugin | property/method | desc | |---|---| | constructor(config) | create new instance |

config

property	desc	type	default
initialChar	single character that represents item in the toolbar	string
tooltip	description of the tool	string
weight	The more weight, the latter the item appears in the toolbar	number
keyAlias	key to invoke the plugin. To learn more about key notation, visit https://codemirror.net/docs/ref/#view.KeyBinding	string
run	action to perform. editorView holds information of the editor, and siteConfig holds configuration of the site. stateModule is a codemirror's state module, which has access to all the classes/constants exported from https://codemirror.net/docs/ref/#state. In most cases, you want to call editorView.dispatch to perform action on editor.	(editorView, siteConfig, stateModule) => void	() => alert("No action is registered for this toolbar item").
isActive	= Plugin.isActive

class TransactionFilter

subclass of Plugin | property/method | desc | |---|---| | constructor(config) | create new instance |

config

property	desc	type	default
map	map key to another key	Map	new Map()
fn	function to perform. Use this field to perform complicated job that you can't with map.	(transaction) => transaction
isActive	= Plugin.isActive