Skip to main content

Markdown Compiler + Server

Project description

Kobo

A hugo-like markdown website/blog builder + server

Features

  • Built with Flask
  • Native support for markdown using katex
  • Lots of out-of-the-box functionality
  • Extensive customization options and extendibility

Installation

  1. Run python3 -m pip install kobo-md
  2. Install katex via npm install katex

See dylwall.com for a sample site built using kobo :)

Usage

  • To start a new project, simply enter the target directory and run python3 -m kobo new.
  • To compile markdown files into html snippets, run python3 -m kobo compile.
  • To run the server, run python3 -m kobo server from the project directory.

Adding Content

  • To create a page on your site, just make a markdown file in the content directory.
  • By default, the route to your page will be the relative path to your file from the content directory.
    • Exception: If your filename is index.md, the route of the page will be the parent directory of the file. For example, content/my-directory/index.md will be routed to /my-directory.
    • If an index.md file is not present in a directory, an index page (but not file) for the directory will automatically be generated.
  • By default, the title of your page will be the filename.

Markdown Options

  • You can override the default route and title of your page by setting them in your markdown file's header.
  • You can also choose what template you want to use for your page in the header (see "Templates" for more info).
  • You can choose to not publish a file by setting the draft option. Here's an example markdown file with these options set:
---
title: My Page
route: /my-page
draft: false
template: homepage.html
---

# Welcome to My Page!

Templates

  • When pages in kobo are processed, they are inserted into Jinja files with a specific format.
  • Index files use the index.html template and all other files use the page.html template by default. You can specify which template to use for a page in the markdown header.
  • Template files are stored in the templates directory.

Running

  • To start up a server, just run python3 -m kobo server!
  • Run python3 -m kobo -h

Custom Configuration and Gunicorn

You can run the kobo flask app in your own scripts by importing kobo.server.create_server:

from kobo.server import create_server
from pathlib import Path

kwargs = {
    # Add your desired keyword arguments here
    'load_from_frozen': True,
    'default_title': "Dylan's Blog"
}

app = create_server(Path('/my/blog/root/directory'), **kwargs)

app.run('0.0.0.0', port=8080)

Alternatively, you can run kobo using gunicorn instead. All you have to do is omit the last line, and run gunicorn -w 2 --bind 0.0.0.0:8000 'main:app'.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kobo-md-0.1.25.tar.gz (12.1 kB view details)

Uploaded Source

File details

Details for the file kobo-md-0.1.25.tar.gz.

File metadata

  • Download URL: kobo-md-0.1.25.tar.gz
  • Upload date:
  • Size: 12.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.7

File hashes

Hashes for kobo-md-0.1.25.tar.gz
Algorithm Hash digest
SHA256 dfa6b5e8434df0a9f378dd1e2f6cd3897617c03cc5583fc5d33fcc45f8326d87
MD5 a21b63877a739f653829188e9161ec65
BLAKE2b-256 5e4b5786f19d3fbae8a897fc13021fc708a3880fd7a286eb0b68be145aa2af98

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page