2023-05-30 22:36:40 +02:00
# mkht.php
2023-09-04 23:31:16 +02:00
mkht.php is a PHP script for building HTML/CSS sites from source documents in PHP, Gemini, Pandoc Markdown, HTML and CSS.
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
2023-09-04 23:31:16 +02:00
Source pages must end in `.md` and can use Markdown, HTML and PHP.
2023-09-20 22:24:58 +02:00
The following 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
2023-09-20 22:24:58 +02:00
Files starting with a dot (except for `.htaccess` ) 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.
Security note: as PHP code is executed, input files need to be trusted
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/*.gmi` (if using `.gmi` extension in /src)
* `/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-05-30 22:36:40 +02:00
## External dependencies
2021-10-09 20:13:55 +02:00
* PHP
* gzip
2023-05-24 18:58:56 +02:00
* pandoc
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 / > .
