Please refer to the tutorial for more details on usage.
If you want to start off with a working example project, You can use our provided examples:
All you need to do is upload the contents of these into your /source folder and press "build" in your panel.
Example project setups can be found inside the /example folder:
/example/hello-worldThe absolute minimum required to get your project going/example/basicA goof starting off point. It has things configured like- The
bloglikeplugin. This enables you to have a blog, or something similar - A custom plugin for enabling LaTeX notation in markdown.
- A layout with some CSS (internal + external) to make it look presentable
- A favicon and some public folders / images
- The
routesdefine all your routes, keys are absolute paths (on the target blog), settings are:use: "/path"the folder containing the markdown files (relative to the/sourcedirectory). Default is the target path (this objects key). All markdown files in this directory will be rendered to HTML and made public (exceptREADME.md).title: "title with %s placeholder"template for the page titles,%sis replaced with the documents titlecss: "/path/to/css" | [paths]additional css files to be included (either a string, or array of strings). Paths are relative to the css directory/csslayout: "layout.html"Use a special template for this route. Relative to the/sourcedirectoryrecursive: true|falseapply route to all subfolders as well (see "basic" example)plugin: {name: "name", <additional config>}, you can also supply an array or plugin configs.headers: "<header tag>" | [header tags]Additional header elements
layout: "layout.html"title: "template string %s"specify a global title template (gets overwritten by route-specific configurations)themes: ["theme1", "theme2", ...]list of theme namesheaders: "<header tag>" | [header tags]Tags to append to your html<head>authtokens: ["key1", "key2", ...]list of authentication keys. When set, building requires authentication with one of these keys.external_plugins: true|falseUse custom plugins defined in the/source/pluginsfolderformatting: {date: <php date formattin>, time: <format>, datetime: <format>}define formatting for displaying and parsing dates. Default is"formatting": { "date": "d.m.Y", "time": "H:i", "datetime": "d.m.Y - H:i" }fetch: An array of pairs of urls and locations in the filesystem of files that have to be downloaded from the Web before the build starts. An example element of the array looks like{ "source": "https:/example.org/file.zip", "target": "public/downloads/file.zip" }
To activate a Sync from a Dropbox folder, create the JSON-File source/.dropbox-login.json with a content in the following format:
{
"clientId": "xxxxxxxxxxxxxxx",
"clientSecret": "xxxxxxxxxxxxxxx",
"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"rootFolder": "/Daten - Fachschaft Mathe/Website/koma84/"
}
- Before every build, the complete content of the Dropbox-folder specified will be downloaded.
- Files that were synced from Dropbox will be deleted as soon as they are deleted in the Dropbox.
- If
source/.dropbox-login.jsondoes not exist, this step will be skipped.
An example folder structure might be:
source/
|-- css/ -> your css files
|-- base.css -> your base css file
|-- *.css -> all other .css files will be linked into /css
|-- blog/ -> files for a defined route
|-- article1.md -> a blog article
|-- article2.md -> next blog article
|-- ... -> ...
|-- public/ -> public files, will be linked to /public
|-- fonts/ -> fonts, images, etc can be put here
|-- images/ -> these are then available in /public/images/
|-- scripts/ -> of course you can also embed scripts
|-- ...
|-- plugins/ -> your custom plugins
|-- plugin1.php
|-- plugin2.php
|-- ...
|-- index.md -> Website index
|-- config.json -> your config json
|-- layout.html -> your layout file
|-- different-layout.html -> another layout file
|-- favicon.ico -> your favicon, this will be linked to /favicon.ico
|-- .htaccess -> protect your config (containing deploy keys)
build the image: sudo docker build -t mssg .
then run
sudo docker run -it -p 8000:80 \
-v /path/to/your/source:/var/www/html/source \
-v /path/to/your/system:/var/www/html/system mssg "/root/start-script.sh"to
- bind port 80 from the container to port 8000 on your machine
- link your
sourcefolder to thesourcefolder in the container - do the same thing for the
systemfolder - run the startup script (which will drop a bash shell)
You can omit the system line if you don't plan on changin anything with the system.
Available hooks: ($config refers to plugin config, the route config can always be found in $config['..'])
before_route($config, $target_path)called before route is started, here you can modify the route configbefore_parse($config, $raw_content, $file, $metadata)called right before the markdown gets rendered - you can change$fileto change the target file name.after_parse($config, $content, $file, $metadata)called right after the markdown gets rendered - you can change$fileto change the target file name.after_route($config, $pages, $write_to_file, $parse)to create other files like a generatedindex.htmlfile - called after every file was rendered$pagescontains metadata, title (rendered through template), url, filename and contents (as html).$write_html_file($file, $content, $title)is a funcion that writes the content to the specified html file and applies the current layout$parse($markdown)renders markdown to html$write_file($file, $content)is a function that writes the content to the specified file
If you want to add a plugin, create a new php file in /source/plugins. Use the define_plugin($name, $methods) function like this to add a new plugin named "your-plugin":
<?php
define_plugin("your-plugin", [
"before_parse" => function ($config, &$raw_content, $file, $metadata) {
$raw_content .= "\n **custom plugin footer**";
}
]);
?>And in your config.json add "plugin": {"name": "your-plugin"} for a specific route. This will append <strong>custom plugin footer</strong> to every page on that route.
- For parsing markdown we use: michelf/php-markdown
- Dropbox sync is built with kunalvarma05/dropbox-php-sdk (licensed under MIT)
- For parsing ICS files (calendar plugin) johngrogg/ics-parser (licensed under MIT)