Please refer to the documentation provided in the README.md,
Project description
wikme
wikme is a Python package that allows you to convert a folder of Markdown files into a simple wiki-style website. It supports parsing and converting wikilinks, both regular and with custom titles, and includes additional features like last edited date retrieved from git log or file modification timestamp, depending on your needs.
Features
- Convert a folder of Markdown files into a simple wiki-style website
- Automatically handles wikilinks and converts them to HTML anchor tags
- Supports custom titles for wikilinks
- Detects last edited date, either from Git log or file modified timestamp
- Allows users to provide their own HTML templates for a customized look and feel
Installation
You can install the package via pip:
pip install wikme
Usage
You can use wikme package in your Python scripts as follows:
from wikme import main
# Define input and output directories and the template file
input_folder = "./markdown_files/"
output_folder = "./generated_html/"
template_file = "./template.html"
main(input_folder, output_folder, template_file)
You can also use it as a command-line tool:
wikme --input "./markdown_files" --output "./generated_html" --template "./template.html"
Arguments
--input: Path to the input folder containing the Markdown files.--output: Path to the output folder where the generated HTML files will be saved.--template: Path to the HTML template file used for rendering the Markdown files.
HTML Template
You can create a custom HTML template to style the generated files. The content of the Markdown files will be inserted into the designated placeholder.
An example template:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ title }}</title>
<link rel="stylesheet" href="pygment.css">
</head>
<body>
<header>
<h1>{{ title }}</h1>
</header>
<main>
{{ content }}
</main>
<footer>
<small>Last Edited: {{ last_edited }}</small>
</footer>
</body>
</html>
Placeholders:
{{ title }}: Will be replaced with the title of the Markdown file.{{ content }}: Will be replaced with the HTML converted content of the Markdown file.{{ last_edited }}: Will be replaced with the last edited date of the file.
Wikilinks Syntax
Wikilinks are used to create links between pages within the generated wiki-style website. The wikme package supports several variations of wikilink syntax.
Regular Wikilinks
- Standard wikilinks without custom titles:
[[Page Name]]
This syntax will create a link to the specified page with the same text as the page name.
Example: [[Home Page]] creates a link to the "Home Page" with the text "Home Page".
- Wikilinks with custom titles:
[[Page Name|Custom Title]]
This syntax allows you to create a link to a page with a custom display text for the link.
Example: [[Home Page|Visit our home page]] creates a link to the "Home Page" with the text "Visit our home page".
Tilde-prefixed Wikilinks
These are useful when you want to link to files outside of the input folder or link to a different directory assuming you are on a pubnix or tilde server.
- Tilde-prefixed wikilinks without custom titles:
[[~path/to/page]]
Example: [[~docs/section-01]] creates a link to the "/docs/section-01" page with the text "docs/section-01".
- Tilde-prefixed wikilinks with custom titles:
[[~path/to/page|Custom Title]]
Example: [[~docs/section-01|Section 1]] creates a link to the "/docs/section-01" page with the text "Section 1".
Notes
The parser will process the wikilinks within your Markdown files and convert them into the corresponding HTML anchor tags.
Syntax Highlighting and CSS Generation
The wikme package renders Github Flavoured Markdown. This is easily highlighted using highlight.js. See test_template.html for an example.
Syntax Highlighting in Markdown
To enable syntax highlighting for a code block, you can use the the 4 space indent syntax with a language identifier. Here's an example:
Check out this code:
#!python
msg = "Hello, world"
print(msg)
In this example, the language identifier is python. This will tell the codehilite extension to apply syntax highlighting for the Python language to this code block.
You can use any language identifier supported by the Pygments library. A list of supported languages can be found in the Pygments documentation.
Generating CSS for Syntax Highlighting
The codehilite extension uses the Pygments library for syntax highlighting. To generate a CSS file for syntax highlighting, you can use the pygmentize command-line tool provided by the Pygments library.
First, ensure that you have the 'Pygments' library installed. You can install it using pip:
pip install pygments
Next, you can generate the CSS file with the following command:
pygmentize -S <style-name> -f html -a .codehilite > pygment.css
Replace <style-name> with the desired syntax highlighting style. Some popular style names include default, monokai, vs, and xcode. A list of available styles can be found in the Pygments documentation.
This command generates a pygment.css file with the selected style applied to the codehilite class. You can include this CSS file in your HTML template to enable syntax highlighting for your generated wiki-style website.
License
MD GPL
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file wikme-1.1.3.tar.gz.
File metadata
- Download URL: wikme-1.1.3.tar.gz
- Upload date:
- Size: 514.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: python-requests/2.28.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fc2055e9fdf98a9ca15b422ed3ee3215194425b2ca36b4a9235ddeb1fcf36e3b
|
|
| MD5 |
9747062eeab0e02c0ec4d6322d8cd13f
|
|
| BLAKE2b-256 |
088f89925559e8bcd6f4e2f8a9be0bdd16be0fc73945d3486072b799bae9b705
|
File details
Details for the file wikme-1.1.3-py2.py3-none-any.whl.
File metadata
- Download URL: wikme-1.1.3-py2.py3-none-any.whl
- Upload date:
- Size: 5.1 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: python-requests/2.28.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
547e3f70ec3ad013549cebabb7e9d52d42d13548acfe1bbb503b314cc0403f2c
|
|
| MD5 |
cbd97d571714fdeb048c0eae6baf4513
|
|
| BLAKE2b-256 |
c24eb99f948b7db7ab298555fc0678fde2d93bc677f6fe62baced2002205be0e
|
