You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

120 lines
6.1 KiB

4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
  1. This is a Static Site Generator.
  2. In many cases a CMS doesn't need to generate each page again and again for each request.
  3. This is an attempt to generate Static HTML from Twig Templates.
  4. # Setup
  5. * `git clone`
  6. * `composer install --no-dev`
  7. * `cp settings.php.dist settings.php`
  8. # Config
  9. Edit `settings.php` and change `BASE_PATH` accordingly.
  10. Depending on your webserver, you can change `REDIRECT_METHOD` to one of the following:
  11. * `REDIRECT_METHOD_NONE`
  12. * `REDIRECT_METHOD_HTACCESS`
  13. * `REDIRECT_METHOD_PHP`
  14. * `REDIRECT_METHOD_HTML`
  15. * `REDIRECT_METHOD_SYMLINK`
  16. This will change the way, the user is redirected from `altSlugs` (see section "Advanced page features") to the primary URL of a page.
  17. `REDIRECT_METHOD_HTACCESS` obviously will only work with Apache. `REDIRECT_METHOD_PHP` obviously will only work with a PHP-capable webserver.
  18. `REDIRECT_METHOD_HTML` will generate HTML files that redirect the user via `<meta>` tags and JS. `REDIRECT_METHOD_SYMLINK` will just symlink the file so basically no redirect will happen.
  19. Depending on your webserver, you can change `CONTENTTYPE_OVERRIDE_METHOD` to one of the following:
  20. * `HEADER_OVERRIDE_METHOD_NONE`
  21. * `HEADER_OVERRIDE_METHOD_HTACCESS`
  22. * `HEADER_OVERRIDE_METHOD_PHP`
  23. This will change the way, the HTTP headers of pages are overridden. This is only required for example for RSS Feeds etc. where you want a different HTTP Header than the ones guessed by the webserver.
  24. again: `HEADER_OVERRIDE_METHOD_HTACCESS` obviously will only work with Apache. `HEADER_OVERRIDE_METHOD_PHP` obviously will only work with a PHP-capable webserver.
  25. Set `IMAGE_RESIZE_METHOD_*` to define the scaling method for resizing images:
  26. * `IMAGE_RESIZE_METHOD_NONE` disables image resizing. useful if you don't want to change all templates
  27. * `IMAGE_RESIZE_METHOD_WIDTH` resizes the image to the specified width and keeps the aspect ratio
  28. * `IMAGE_RESIZE_METHOD_HEIGHT` resizes the image to the specified height and keeps the aspect ratio
  29. * `IMAGE_RESIZE_METHOD_BEST` resizes the image to best fit inside the given dimensions. (format: "$width,$height" or [$width, $height] in PHP7)
  30. there are some more constants that can be set but usually this is not required.
  31. # Usage
  32. ![example](https://dev.tsia.de/htmlengine/static/example.png)
  33. run `./index.php --help` for a brief list of commands:
  34. ```
  35. Usage:
  36. --run render and switch to new version
  37. --no-switch render and don't switch to new version
  38. --switchonly don't render and only switch to new version (use after --no-switch)
  39. --rollback switch to previous version
  40. --switch-to VER switch to version VER
  41. --list-versions list available versions
  42. --cleanup N delete old versions but keep the latest N
  43. ```
  44. `./index.php --run` will generate a folder structure, render all templates and place the HTML into the appropriate folder.
  45. by default the latest generated files will be accessible via the symlink `versions/current`. Your webserver should use that symlink as webroot.
  46. [example output](https://dev.tsia.de/htmlengine/)
  47. (my [blog](https://tsia.me) now also runs this)
  48. # Versions
  49. every time you run `./index.php --run`, a new version will be created in the `versions`-folder. you can list them with `./index.php --list-versions` to see what version is currently active.
  50. you can switch versions with `./index.php --switch-to` or `./index.php --switchonly`.
  51. You can use `./index.php --no-switch` to generate the new templates but not switch them to `current`. Instead a symlink `next` will be created. use this to preview the new site for example at a different subdomain before switching it to production.
  52. In case something goes wrong, you can use `./index.php --rollback` to switch to the previous version. Note: only one rollback at a time is supported. to switch further, use `./index.php --switch-to ...`
  53. # Creating pages
  54. rendering is done by just parsing all files under `templates/THEME/pages/*.twig` with twig. the url is inferred from the file name of the template.
  55. `templates/THEME/pages/post1.twig` will be available at the URL `/post1`.
  56. you can use sub-folders inside of `templates/THEME/pages/` if you like. they don't change the behaviour in any way.
  57. # Advanced page features
  58. if a ini-file with the same name as the template exists, it is read. example file:
  59. ```
  60. [settings]
  61. slug = "faq"
  62. enabled = 1
  63. [headers]
  64. 0 = "Content-Type: text/plain"
  65. [altSlugs]
  66. 0 = "help"
  67. [variables]
  68. headline = "FAQ & Help"
  69. ```
  70. * `slug`: this will be the URL
  71. * `enabled`: if not true, the page won't be rendered
  72. * `[altSlugs]`: list of alternative URLs. Users will be redirected to the primary `slug`
  73. * `[variables]`: those variables will be available in the template
  74. see example templates for more details how to use twig template extension, blocks and variables to re-use templates.
  75. # special twig functions
  76. use the special twig function `getPageContent($slug, $block = 'entry')` to get rendered page contents. This can be used to embed single blocks of a page somewhere else.
  77. use the special twig function `getPageMeta($path, $sort, $limit, $desc)` to get a list of page metadata from their ini files. This can be used to create a listing of pages for example with title, link etc.
  78. use `$path` to limit the list to only those templates inside a specific template folder.
  79. use `$sort` to sort the pages by a specific item in their ini files.
  80. use `$limit` to limit the amount of pages to fetch.
  81. use `$desc = false` to sort them ascending instead of decending.
  82. use the special twig function `imageresize($image, $size)` to get resized images.
  83. define the constants `IMAGE_RESIZE_METHOD_$size` and `IMAGE_SIZE_$size` accordingly
  84. # advanced settings
  85. `define('DIR_MODE', 0755)` permissions of newly created folders.
  86. `define('OUTPUT_DIR', __DIR__ . '/versions')` the folder where to put the rendered pages. no trailing slash.
  87. `define('BASE_PATH', 'http://localhost/')` the base path used to generate absolute URLs in templates and redirects. don't forget the trailing slash.
  88. `define('THEME', 'example')` the name of the theme to use.
  89. `define('STATIC_FOLDER', 'static')` the name of the folder where static files like css are copied to.
  90. # ghost import
  91. see import.php and modify according to your needs