902cc78782 | ||
---|---|---|
src | ||
.gitignore | ||
Cargo.toml | ||
README.md |
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 otherwiseexport [--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()
andexpect()
) - 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!