fast and simple flat wiki system from markdown
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Milo Fultz 76c04bcc0f Add to roadmap 3 months ago
modules Fix for local links with raw 4 months ago
.coverage Add code coverage, refactor tests 3 months ago
.gitignore Add test pages to ignore 1 year ago
README.md Add to roadmap 3 months ago
requirements.txt Add syntax highlighting 1 year ago
swiki.py Add code coverage, refactor tests 3 months ago
test.py Add code coverage, refactor tests 3 months ago

README.md

{{SWIKI}}

Make a wiki with backlinking from Markdown fast.

Installation

  • Clone the repo.
  • Install requirements with pip: pip install -r requirements.txt

Usage

The Swiki takes in any folder of markdown files and a frame.html file to build a flat-file wiki system. Here's what you'll need:

Pages

The necessary format for your pages are Markdown files with YAML/Jekyll front matter.

  • The front matter currently uses the title and description fields. Note that these are case sensitive. Each page must have a unique name, once all special characters have been removed.
  • Wiki-style links use {{double curly braces}} and are case insensitive. They can be made two ways (note that they reference the title in the front matter, not the filename):
    • {{example}} - Displays the text 'example' and goes to the page whose title is 'example'.
    • {{shown text|example}} - Displays the text 'shown text' and goes to the page whose title is 'example'.

Raw/Escaped Text

Enclosing a section within "raw" tags will allow any double curly braces within that section to remain, never becoming a link. For example, {{% raw %}}An {{example}}{{% endraw %}} escapes the double curly braces and allows An {{example}} to be printed verbatim and not as a link in the rendered page.

Special Characters

These special characters in page titles end up being removed when converting to a filename: /()'".!?,

Non-Markdown Files

Any files that exist in your input directory or any subdirectories will be copied to the root directory of the output directory. Useful for linking to images, code files, or anything else you want to link to directly.

_swiki Directory

Create a directory named _swiki in your input directory. This is where you will put the following files.

_swiki
 ├─ frame.html
 ├─ styles.css
 ├─ index.md
 └─ config.ini

Frame

A frame.html file in the _swiki directory with all of your markdown files. This accepts {{title}}, {{description}}, and {{content}} tags, to fill in the title and description from the page's front matter and the content of the page. A sitemap will also be rendered at index.html, so you can link to that, too.

Tags Description
{{title}} Title described in the front matter of your index.md file
{{description}} Description described in the front matter of your index.md file
{{content}} The content within your index.md file

Here is an example that includes basic CSS to make a generally good looking and easy to read webpage.

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <meta name="description" content="{{description}}">
    <title>{{title}}</title>
    <style>
        html, body {
          margin: auto;
          max-width: 38rem;
          padding: 2rem;
        }
    </style>
</head>
<body>
    {{content}}

    <footer>
        <a href="index.html">Sitemap</a>
    </footer>
</body>
</html>

CSS File

Instead of using a <style> tag in your frame file for styling, you can also link in CSS files. If you include CSS files in the _swiki folder, it will be copied over to the root of your output folder. For instance, if you had a file named styles.css and a file named altstyle.css in your _swiki folder, you could replace your <style>...</style> tags with <link rel="stylesheet" href="./styles.css"><link rel="stylesheet alternate" href="./altstyle.css" title="Cool style">.

Index/Sitemap

By default, index.html will be rendered in your wiki with a title of "Sitemap". The sitemap is organized by the structure of your markdown pages and which folders they reside in (e.g. a file in the root folder will be in a different section than a file in a subfolder). Any page that is linked to but does not yet exist will be in its own section at the bottom of the sitemap as a "stub".

To customize the title, description, and basic content preceding the sitemap, a file named index.md can be used.

---
title: Website Title
description: This will become the meta description.
---

This will be prepended to the sitemap/index of your wiki.

Config File

A config.ini file can be used to overwrite certain parser parameters. For example:

key_one = Value
key_two = 123
Key Effect Default Value
recent_list Whether to build the recent list into the sitemap False
recent_list_length How many items should be included in the recent list 10
tab_size How many spaces a tab character wil be converted to when parsing the page content 2

Rendering

To render your wiki, run the script with the following syntax:

python3 swiki.py input_folder output_folder [flags]
Flag Effect
--delete-current-html, -d Non-recursively delete all existing HTML files in the build directory
--recent-list, -rl Create a recent changes list
--recent-list-length [n], -rll [n] Set the length of the recent list to n entries
--verbose, -v Print debug information during build to build.log. Use -vv for (many) more details

Recent List

A list of recent changes will be created and placed below the content found in index.md, if provided.

Ignoring Files and Folders

Any files or folders with a preceding underscore will be ignored in the rendering process.

Example

---
title: Rendering A Page
description: This will become the meta description.
---

This is the content of the {{Markdown}} file. This {{Markdown reference|Markdown}} doesn't exist, but the {{page}} will.

This would render out five files, all using the frame:

  • index.html - The index and sitemap, containing the rendered contents of index.md and a sitemap of all three above pages.
  • rendering-a-page.html - The file you see above.
  • markdown.html - This file exists with only backlinks, as no file with a title of 'Markdown' exists.
  • page.html - This file exists with only backlinks, for the same reason.

Future Improvements

  • Add IDs to all header elements. e.g. "# Syntax" would be <h1 id="Syntax">Syntax</h1>
  • Add tags for categorical linking by meta ideas, like "#activities", etc.
  • Make the index page have nested and indented subcategories (details/summary) instead of flat.