84 lines
2.8 KiB
Markdown
Executable File
84 lines
2.8 KiB
Markdown
Executable File
# 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](https://po4a.org/) 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
|
|
|
|
IDs are attributed to titles according to their content, therefore modifying a title breaks links to page sections.
|
|
|
|
### 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.
|
|
|
|
## Dependencies
|
|
|
|
* PHP
|
|
* gzip
|
|
* pandoc for Markdown → HTML
|
|
* [po4a](https://po4a.org/) for Gettext translation
|
|
|
|
## License
|
|
|
|
[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.
|
|
|
|
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/>.
|