Metadata-Version: 2.4
Name: warhol
Version: 1.0.0
Summary: Website Assembler Requiring Hardly any Other Libraries -- a minimal static-site builder
Author-email: Andy Buckley <andy@insectnation.org>
License-Expression: Apache-2.0
Project-URL: Repository, https://gitlab.com/agbuckley/warhol.git
Project-URL: Issues, https://gitlab.com/agbuckley/warhol/-/work_items
Project-URL: Changelog, https://gitlab.com/agbuckley/warhol/-/blob/main/CHANGELOG.md
Keywords: html,web,static,website,template,website builder,static site
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown
Provides-Extra: md
Dynamic: license-file

# Warhol — Website Assembler Requiring Hardly any Other Libraries

## Make a website from Markdown and HTML snippets

Current popular static-website generators are complex beasts, with
advanced templating languages, and complicated, fragile and
(e.g. Node) dependency-heavy example styles. This package is the
antidote: a simple, minimal-dependency package for wrapping HTML and
Markdown content pages in site-standard header/footer/etc.
snippets. It's HTML, not rocket science.


### Installing Warhol

As you probably expect, use a recipe like `pip install warhol` or
`python -m pip install warhol` to install from the PyPI archive.

There isn't a way with Python packages to specify a build option
that *reduces* the default number of dependencies, and as almost
everyone will want Markdown format support the Python `markdown`
is the sole installation dependency. If you actively want to
avoid that, pass `--no-deps` to the installation command, and you
can still use Warhol to assemble websites from pure-HTML chunks.


### Using Warhol

Use `warhol init` to initialise a project directory with the basic
structure and a simple template.

The `warhol build` command merges pages from the `content/` directory with
headers, footers, and box "asides" loaded from the `include/`
directory. Any Markdown `.md` files in the content directory tree are
converted to HTML, and staged in the `.build` directory. The final stage
is injection of includes and template parameters, which augment the
cache contents and write out to the `public/` directory.

Parameters are mostly defined as URL-regex maps in the `config.toml`
config file. The default behaviour is for the build step to create a
directory and `index.html` file in place of each (non-index) HTML
file, so the webpage URLs do not have `.html` suffixes; this can be
disabled via a regex match in the config file.

The generated site in the `public/` directory can be viewed directly
with a web browser, but as URLs are internally specified relative to
the HTTP server root and `index.html` pages are assumed to be
implicitly loaded, it's best to run a local web server. The `warhol
serve` command does this, from the `public/` dir by default.


### Example

First, install warhol. Make and activate a virtual environment, then e.g.
```sh
$ python -m pip install warhol[md]
```
to install warhol with Markdown support.

Let's make a new site using the default template:
```sh
$ warhol init mysite -t
$ ls mysite/
content  include  warhol.toml
$ cd mysite/
```

You can edit the include components in the `include/` dir, and customise
how they are used by editing the `warhol.toml`. But just functionally,
let's build the site:
```sh
$ warhol build
$ ls
content  include  public  warhol.toml
```

Note that the new `public/` directory has appeared; this is your website, ready to use:
```sh
$ ls public/
favicon.ico  images  index.html  md  navbar.js  style.css  sub
```

For testing, run the local server:
```sh
$ warhol serve
Serving site from public/ at http://0.0.0.0:8080
Press Ctrl-C to stop serving...
```
and point your web browser at the given URL (something like Ctrl-click
on the link in the terminal may work.)

You might like to run this like `warhol serve &` or otherwise put the
process in the background. Another little hack is that if you like the
rebuilds to happen continually, so you don't have to keep running the
`build` command (and your site builds quickly), try `watch warhol
build` once the server is running, and you can reload the browser
~immediately after saving file-changes.

When happy, deploy manually using your file-transfer tool of choice, e.g.
```sh
$ rsync -r public/ my.webhost.com/public_html/
```


### TODO's
 - add Python smartypants rendering option, opt dependency
 - add a "deploy" command to execute a saved upload destination / command?
 - add code formatting in Markdown... with Python pygments
 - add RST rendering via Python docutils
 - blog mode with date-indexed pages, maybe tags?
 - allow Markdown-based includes? Would require a restructure, but...
 - test and early-exit for either markdown or pandoc if .md's found
 - allow replacement of the site-root leading slash with a configurable string
 - allow regex capture-group injection into templates... needs subst map?!?
 - parallel processing for MD -> HTML
 - unify build and serve modes behind a single command?
 - is there a use for JustHTML or BeautifulSoup?
 - use inotify to auto-trigger updates?
 - single-source the version string for PyPI.
