| modules | ||
| .gitignore | ||
| README.md | ||
| requirements.txt | ||
| requirements_dev.txt | ||
| swiki.py | ||
| test.py | ||
{{SWIKI}}
Quickly make a wiki with incoming links using Markdown.
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
titleanddescriptionfields. 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: /()'".!?,
Other Files
Any non-markdown files or files whose first character in their filename is _ that are 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, raw markdown 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
├─ index.md
└─ config.ini
Any other CSS or JS files from this folder will be copied into the output directory on build.
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>
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body>
{{content}}
<footer>
<a href="index.html">Sitemap</a>
</footer>
</body>
</html>
CSS and JS Files
The style.css file referenced in the above example should be placed in the _swiki folder, along with any other CSS or JS files you want to have in your output folder.
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 ofindex.mdand a sitemap of all three above pages.rendering-a-page.html- The file you see above.markdown.html- This file exists with only incoming links, as no file with a title of 'Markdown' exists.page.html- This file exists with only incoming links, 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.