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 hashes)

Uploaded Source

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