mkht.php/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.

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/>.
Generate Atom feeds (+ delete Parsedown) 2023-05-30 20:36:40 +00:00			`# mkht.php`

add support for po4a translations 2024-01-15 18:55:39 +00: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.`
Move / to /target and /src to / 2023-09-04 21:31:16 +00:00
readme: add sites list and better warning 2024-07-29 00:31:22 +00:00			`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.`
Initialize repository 2021-10-09 18:13:55 +00:00
Generate Atom feeds (+ delete Parsedown) 2023-05-30 20:36:40 +00:00			`## Usage`
Initialize repository 2021-10-09 18:13:55 +00:00
Move / to /target and /src to / 2023-09-04 21:31:16 +00:00			Place your pages tree in `/*.md`.

			`mkht.php [-f] [site_path] [destination]`
Initialize repository 2021-10-09 18:13:55 +00:00
Move / to /target and /src to / 2023-09-04 21:31:16 +00:00			`-f` forces generation of every file, erasing already generated files.
Initialize repository 2021-10-09 18:13:55 +00:00
Move / to /target and /src to / 2023-09-04 21:31:16 +00:00			If `site_path` is not set, it will default to current directory.
Initialize repository 2021-10-09 18:13:55 +00:00
Move / to /target and /src to / 2023-09-04 21:31:16 +00:00			`destination` is optional and can be:
			* `onion` if you want links ending with .onion when available (function `clearnetOrOnion`)
Initialize repository 2021-10-09 18:13:55 +00:00
Generate Atom feeds (+ delete Parsedown) 2023-05-30 20:36:40 +00:00			`## Input`

add support for po4a translations 2024-01-15 18:55:39 +00:00			Source pages must end in `.md` and can use Gemtext, Markdown, HTML and PHP.
Move / to /target and /src to / 2023-09-04 21:31:16 +00:00
add support for po4a translations 2024-01-15 18:55:39 +00:00			`The following optional files have special meaning:`
Move / to /target and /src to / 2023-09-04 21:31:16 +00: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>`
Initialize repository 2021-10-09 18:13:55 +00:00
add support for po4a translations 2024-01-15 18:55:39 +00:00			`/po4a.cfg`
			`: [po4a](https://po4a.org/) configuration file`

Don't ignore .well-known 2023-11-24 19:49:37 +00:00			Files starting with a dot (except for `.htaccess` and `.well-known`) are ignored.
Initialize repository 2021-10-09 18:13:55 +00:00
Move / to /target and /src to / 2023-09-04 21:31:16 +00:00			Files containing `draft` in their name (separated from other characters by `.`) are ignored.

Add links to choose page language 2023-10-14 23:18:44 +00:00			Security note: any PHP code in input files is executed with the same permissions as `mkht.php`
Generate Atom feeds (+ delete Parsedown) 2023-05-30 20:36:40 +00:00
			`## Output`
Initialize repository 2021-10-09 18:13:55 +00:00
Move / to /target and /src to / 2023-09-04 21:31:16 +00:00			* `/target/*.md`
			* `/target/*.html`
			* `/target/*.html.gz`
Initialize repository 2021-10-09 18:13:55 +00:00
			`Note that format translation is only done in the following order:`
Generate Atom feeds (+ delete Parsedown) 2023-05-30 20:36:40 +00: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.)`

Move / to /target and /src to / 2023-09-04 21:31:16 +00:00			`## Metadata persistence`
Generate Atom feeds (+ delete Parsedown) 2023-05-30 20:36:40 +00:00
fix atom updated element + detect YYYY-MM-DD-* 2024-06-27 15:59:09 +00:00			`HTML IDs are attributed to headings according to their content, therefore modifying a title breaks links to page sections.`
Generate Atom feeds (+ delete Parsedown) 2023-05-30 20:36:40 +00:00
			`### For atom feeds`

fix atom updated element + detect YYYY-MM-DD-* 2024-06-27 15:59:09 +00:00			* 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.`
Initialize repository 2021-10-09 18:13:55 +00:00
Don't ignore .well-known 2023-11-24 19:49:37 +00:00			`## Dependencies`
Initialize repository 2021-10-09 18:13:55 +00:00
			`* PHP`
			`* gzip`
add support for po4a translations 2024-01-15 18:55:39 +00:00			`* pandoc for Markdown → HTML`
			`* [po4a](https://po4a.org/) for Gettext translation`
Initialize repository 2021-10-09 18:13:55 +00:00
Generate Atom feeds (+ delete Parsedown) 2023-05-30 20:36:40 +00:00			`## License`
Initialize repository 2021-10-09 18:13:55 +00: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.`

Add lang in config.ini 2021-10-11 22:03:18 +00: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/>.`