beenull/mkht.php
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Hypertext sites generator
40 commits 1 branch 0 tags 200 KiB
PHP 63.1%
CSS 36.9%
Find a file
Miraty c40470d3de fix atom updated element + detect YYYY-MM-DD-*
2024-06-27 17:59:09 +02:00
config.template.ini Document gzip setting in config.template.ini 2024-03-13 00:05:40 +01:00
LICENSE Initialize repository 2021-10-09 20:13:55 +02:00
mkht.php fix atom updated element + detect YYYY-MM-DD-* 2024-06-27 17:59:09 +02:00
README.md fix atom updated element + detect YYYY-MM-DD-* 2024-06-27 17:59:09 +02:00
style.css Don't ignore .well-known 2023-11-24 20:50:46 +01:00

README.md

mkht.php

mkht.php is a PHP script for building HTML/CSS sites from source documents in PHP, Gemtext, Pandoc Markdown, Gettext translation files, HTML and CSS.

For my personal use cases, this project include some specific tweaks that may not be fully or correctly documented.

Usage

Place your pages tree in /*.md.

mkht.php [-f] [site_path] [destination]

-f forces generation of every file, erasing already generated files.

If site_path is not set, it will default to current directory.

destination is optional and can be:

  • onion if you want links ending with .onion when available (function clearnetOrOnion)

Input

Source pages must end in .md and can use Gemtext, Markdown, HTML and PHP.

The following optional files have special meaning:

/config.ini
some default settings can be changed by this file
/style.css
additional CSS
/head.inc.html
added just before </head>
/header.inc.php
added just after <body>
/end.inc.html
added just before </body>
/po4a.cfg
po4a configuration file

Files starting with a dot (except for .htaccess and .well-known) are ignored.

Files containing draft in their name (separated from other characters by .) are ignored.

Security note: any PHP code in input files is executed with the same permissions as mkht.php

Output

  • /target/*.md
  • /target/*.html
  • /target/*.html.gz

Note that format translation is only done in the following order: Gemini > Markdown > HTML, which means that the last of these formats you will use will be the first that will be readable by hypertext browsers. (PHP is always executed first.)

Metadata persistence

HTML IDs are attributed to headings according to their content, therefore modifying a title breaks links to page sections.

For atom feeds

  • Except when a page name start with a date formated as YYYY-MM-DD-, the updated element of each Atom entry is determined by the modification timestamp of the source file. If using cp to backup or transfer files, its --preserve=timestamps option should be added.
  • Renaming/moving a page creates a new page and deletes the older.

Dependencies

  • PHP
  • gzip
  • pandoc for Markdown → HTML
  • po4a for Gettext translation

License

AGPLv3+

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.