README

pipeline status latest release

IMMS is a kind of SSG (Static Site Generator), but without you having to build it yourself and entirely without pipelines.

It takes your Markdown and renders it as HTML in a file cache, and serves this HTML without having to re-render it again. This makes IMMS pretty fast at serving content.

If you have HTML files instead of Markdown files, it will simply stitch the HTML content together with overall template files, and cache the final result. Again, making IMMS pretty fast at serving content.

If you need help or want to learn more, please check out the wiki.

Intended use cases

To serve a repository with markdown or HTML files (such as a GitHub/GitLab wiki!)
To serve as an SFTP server for your old pals to host their static HTML (docker image supports this out of the box!)
Other semi- to fully static content

There's quite literally no fuss (or very little of it):

No database
No users that need to log in
No need for manual cache handling
No built-in editors

Features

GitHub Flavoured Markdown
- This is just the base; it should have almost full support for Gitlab Flavoured Markdown as well
Header Permalinks
Syntax highlighting for code blocks
Hints
Text Highlighting (Remember those yellow highlighters?)
Youtube iframes
Emojis
Image attributes (size them however you want!)
WikiLinks
Sub pages
- Create a directory with the same name of a markdown file
- Add markdown files into the directory
- IMMS will link the markdown file and directory together automatically.
Support for special characters in markdown file name
Table of Contents (configurable!)
Automatic caching (and clearing of it!)
A (albeit quite simple) CLI tool
Lazy image loading
Integrated git (this feature must be enabled in config)
You can feed it HTML or Markdown; doesn't matter, it will handle it.
Custom templates (using Plates!)
Custom plugins!

Additional features in Docker

Makes use of PHP's opcache to improve performance
Makes use of Apache's built-in caching, to serve files even faster

Getting started

Docker Compose

An example could be like so:

services:
  imms:
    image: registry.gitlab.com/inuitviking/imms:latest
    ports:
      - 8080:80
      - 2222:2222
    #    expose:
    #      - 1234
    #      - 2222
    environment:
      - APACHE_PORT=1234
      - APACHE_CACHE_AGE=900
      - APACHE_CACHE_SIZE=5M
      - SSH_PORT=2222
      - SSH_USER=imms
      - SSH_PASS=imms
    volumes:
      - ./.docker/documents:/var/www/src/documents
      - ./.docker/config:/var/www/config

./.docker/documents: The place where you store your uploads and markdown files.
./.docker/config: This is where the config.ini file is stored

All of the above is supplied in .docker as examples.

You may also see the Apache config and PHP config within .docker; this is used for building the docker image, to configure opcache and Apache's built-in cache.

The docker image provided makes use of opcache and Apache's included caching system to improve response time.

If you prefer to use the built-in git, you can omit the "documents" volume, as IMMS would then handle the pulling internally.

On a good ol' web server

composer create-project inuitviking/imms
cd imms

Once created, you can configure it to pull HTML/Markdown from a remote repository in config/config.ini.

If you prefer not to do that, make sure to create the necessary directories:

mkdir -p src/documents
touch src/documents/index.md

You may want to take a look at config/config.ini to adjust to your liking.

Dependencies

Composer dependencies:

PHP dependencies

PHP8.3 or newer
ext-dom

Server dependencies

git
composer
php (8.3 or newer)
- ext-dom should also be installed
A webserver
- Apache with the php module
- NGINX with PHP FPM

inuitviking / imms

Maintainers

Details