89 lines
3.3 KiB
Markdown
Executable file
89 lines
3.3 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.
|
|
|
|
This is used to generate the static websites for:
|
|
* Antopie [repo](https://code.antopie.org/Antopie/antopie) [live](https://antopie.org/)
|
|
* ServNest [repo](https://code.antopie.org/servnest/docs) [live](https://servnest.niv.re/)
|
|
* Niver [repo](https://code.antopie.org/Antopie/about-niver) [live](https://about.niv.re/)
|
|
* Miraty [live](https://miraty.niv.re/)
|
|
|
|
This is an accumulation of code designed for my specific use-cases without much consideration for affordance, readability, maintainability or performance. You probably don't want to use it as is for your own sites.
|
|
|
|
## 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
|
|
|
|
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](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/>.
|