2023-05-30 22:36:40 +02:00
# mkht.php
2024-01-15 19:55:39 +01:00
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.
2023-09-04 23:31:16 +02:00
For my personal use cases, this project include some specific tweaks that may not be fully or correctly documented.
2021-10-09 20:13:55 +02:00
2023-05-30 22:36:40 +02:00
## Usage
2021-10-09 20:13:55 +02:00
2023-09-04 23:31:16 +02:00
Place your pages tree in `/*.md` .
`mkht.php [-f] [site_path] [destination]`
2021-10-09 20:13:55 +02:00
2023-09-04 23:31:16 +02:00
`-f` forces generation of every file, erasing already generated files.
2021-10-09 20:13:55 +02:00
2023-09-04 23:31:16 +02:00
If `site_path` is not set, it will default to current directory.
2021-10-09 20:13:55 +02:00
2023-09-04 23:31:16 +02:00
`destination` is optional and can be:
* `onion` if you want links ending with .onion when available (function `clearnetOrOnion` )
2021-10-09 20:13:55 +02:00
2023-05-30 22:36:40 +02:00
## Input
2024-01-15 19:55:39 +01:00
Source pages must end in `.md` and can use Gemtext, Markdown, HTML and PHP.
2023-09-04 23:31:16 +02:00
2024-01-15 19:55:39 +01:00
The following optional files have special meaning:
2023-09-04 23:31:16 +02:00
`/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>`
2021-10-09 20:13:55 +02:00
2024-01-15 19:55:39 +01:00
`/po4a.cfg`
: [po4a ](https://po4a.org/ ) configuration file
2023-11-24 20:49:37 +01:00
Files starting with a dot (except for `.htaccess` and `.well-known` ) are ignored.
2021-10-09 20:13:55 +02:00
2023-09-04 23:31:16 +02:00
Files containing `draft` in their name (separated from other characters by `.` ) are ignored.
2023-10-15 01:18:44 +02:00
Security note: any PHP code in input files is executed with the same permissions as `mkht.php`
2023-05-30 22:36:40 +02:00
## Output
2021-10-09 20:13:55 +02:00
2023-09-04 23:31:16 +02:00
* `/target/*.md`
* `/target/*.html`
* `/target/*.html.gz`
2021-10-09 20:13:55 +02:00
Note that format translation is only done in the following order:
2023-05-30 22:36:40 +02:00
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.)
2023-09-04 23:31:16 +02:00
## Metadata persistence
2023-05-30 22:36:40 +02:00
2023-09-04 23:31:16 +02:00
IDs are attributed to titles according to their content, therefore modifying a title breaks links to page sections.
2023-05-30 22:36:40 +02:00
### For atom feeds
* Make sure modification timestamps of source files are preserved. For example, `cp --preserve=timestamps` must be used instead of just `cp` when backing up or migrating.
* Renaming/moving a page creates a new page and delete the older.
2021-10-09 20:13:55 +02:00
2023-11-24 20:49:37 +01:00
## Dependencies
2021-10-09 20:13:55 +02:00
* PHP
* gzip
2024-01-15 19:55:39 +01:00
* pandoc for Markdown → HTML
* [po4a ](https://po4a.org/ ) for Gettext translation
2021-10-09 20:13:55 +02:00
2023-05-30 22:36:40 +02:00
## License
2021-10-09 20:13:55 +02:00
[AGPLv3+ ](LICENSE )
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.
2021-10-12 00:03:18 +02:00
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 / > .
