A pad manager to save local copies of your pads and export them to static-site generators.
Go to file
user 902cc78782 Update README with more info 2019-07-29 19:02:03 +02:00
src More friendly error message 2019-07-25 13:02:48 +02:00
.gitignore Update gitignore 2019-07-25 13:02:07 +02:00
Cargo.toml Rename to padman 2019-07-25 13:02:16 +02:00
README.md Update README with more info 2019-07-29 19:02:03 +02:00

README.md

padman - a pad manager

⚠️ This is not mature software. It will change a lot so don't rely on it just yet. ⚠️

padman is a simple program to help you manage your collections of pads. Its main intended use-case is to download a collection of pads and export it to a static site generator:

$ padman download "https://hackmd.io/s/book-example"
$ padman export /tmp/book
$ cd /tmp/book
$ zola build -o /var/www/book.example.org

padman is written in Rust because i wanted to learn it while building something useful. The code is amateur-ish at best and should not be considered an example of what good Rust code would look like. If you would like to help me write more idiomatic Rust code (i would love that), please open a merge request.

## Features

padman currently only has two subcommands:

  • download <URL> [file]: download a docbook to a specified file, or to .padman/cache in the current folder otherwise
  • export [--from=file] [--to=folder]: export the Markdown pages from a specified docbook file (or from .padman/cache by default) to a specified folder, or to the current folder otherwise

Content sources

Source Markdown  Links Images padman
HackMD/CodiMD
Etherpad Lite

For the moment, only HackMD and its opensource edition CodiMD can be used with padman. Etherpad Lite is a good candidate for integration. However, Etherpad is currently limited and would limit padman's abilities. These three issues need to be addressed:

  • etherpad does not support hyperlinks in pads: a plugin implements them, but only partially (they are drawn on-screen, but not generated in the exports)
  • etherpad has very bad support for Markdown: a plugin exists but even raw URLs do not produce legit Markdown in the export
  • etherpad has very bad support for embedded images: a plugin exists but image has to be embedded as base64 data within the pad (i.e. you cannot use external images)

To implement a new backend to fetch content, you just have to implement the SourceBackend interface, which defines a fn download(&self, path: &str) -> Option<Page> function. Then use your own structure (let's call it MyBackend) like so:

use docbook::Book;
let mut book = Book::new(MyBackend, "index_page");

Export targets

Currently, only Zola works fine with padman-generated files. That is because some static site tools (such as Hugo) rewrite URLs (removing capital letters), even when you provide it directly in the frontmatter. To deal with such specifics, each export target will need its custom logic which hasn't been written yet.

TODO

There is still a lot to do to make padman enjoyable.

Features:

  • More extensibility (make it easier to implement a source/target backend)
  • CLI parameters to select backend (currently backend is calculated from URL)
  • Support ACLs so we can access private pads
  • a TUI interface?
  • Allow for a padman profile to handle several pad collections? (such as in a ~/.padman)
  • More?

Fixes:

  • Handle internal/external links and path rewrites
  • Avoid crashes (remove unwrap() and expect())
  • Write documentation
  • Write tests

License

This program is a collective property of humanity released under the GNU GPL 3.0+ license.

It is free software: you may use it and modify it however you please as long as you retain authorship and license information. However, if you want to distribute modified versions of the program, you have to distribute the source of the program under the same license so that everybody else can enjoy your contributions as much as you enjoy other people's.

Contributing

Submit a merge request!