https://github.com/gashmob/mdgen
Markdown template engine
https://github.com/gashmob/mdgen
markdown php template
Last synced: 3 months ago
JSON representation
Markdown template engine
- Host: GitHub
- URL: https://github.com/gashmob/mdgen
- Owner: Gashmob
- License: gpl-3.0
- Archived: true
- Created: 2022-08-30T17:37:36.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2022-09-29T11:05:49.000Z (almost 4 years ago)
- Last Synced: 2025-03-02T06:41:30.572Z (over 1 year ago)
- Topics: markdown, php, template
- Language: PHP
- Homepage:
- Size: 121 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# MdGen
[](https://github.com/Gashmob/MdGen/actions/workflows/test.yml)
[](https://wakatime.com/badge/user/c1e2386d-065c-4366-b163-d98f957273dc/project/44c9d956-4bea-471c-8dc6-5752f533022a)
Markdown template engine. This php library will generate html from markdown templates (`*.mdt` file).
- [Usage](#usage)
- [Templates format](#templates-format)
- [Special](#special)
- [Base template](#base-template)
- [Include template](#include-template)
- [Scripting](#scripting)
- [Generate html](#generate-html)
- [Cache](#cache)
- [Installation](#installation)
## Usage
Let see how to use MdGen. If you want some examples, you can go inside test dir, there is the template with the html
result.
### Templates format
First, there is all the format that you can use for your template and how it will be translated to html. Essentially
it's markdown, but there is some difference :
MdGenhtml
```md
# Title 1
```
```html
Title 1
```
```md
## Title 2
```
```html
Title 2
```
```md
### Title 3
```
```html
Title 3
```
```md
#### Title 4
```
```html
Title 4
```
```md
##### Title 5
```
```html
Title 5
```
```md
###### Title 6
```
```html
Title 6
```
```md
Some text
```
```html
Some text
```
```md
[Google](https://www.google.com)
```
```html
Google
```
```md
```
```html
```
```md
**Bold**
```
```html
Bold
```
```md
*Italic*
```
```html
Italic
```
```md
1. First item
2. Second item
```
```html
- First item
- Second item
```
```md
- First item
- Second item
```
```html
- First item
- Second item
```
```md
---
```
```html
```
```md
`code`
```
```html
code
```
```md
```bash
echo "Hello world"
\```
```
Write the end of code block without the backslash.
```html
echo "Hello world"
```
```md
> quote
```
```html
quote
```
```md
| Col 1 | Col 2 | Col 3 |
| :---- | :---: | ----: |
| 1 | 2 | 3 |
```
```html
Col 1
Col 2
Col 3
1
2
3
```
```md
```
```html
```
```md
{foo}
```
```html
bar
```
Replace `{foo}` by the value given at the render function :
```php
$engine->render('myTemplate.mdt', [ "foo" => "bar" ])
```
### Special
But there is some another statements that can be used in your template.
The first of generation is pre-rendering. During these steps the library look at the first lines for a special
statement. These lines specify some values that the pre-render function should return. It will not appear in final html
document. It works on a key value system :
```md
[#]: key -> value
```
The pre-render function will then return :
```php
[
"key" => "value",
]
```
#### Base template
Frequently your templates need the same base in html (same header, same footer, ...). For that you can add this
statement at the beginning of your template (after the key-value)
```md
[#]: base someTemplate
```
The library will then look for the file `someTemplate.mdt` from where the template is located. You can override this by
providing a search path to the library :
```php
$engine->basePath('someWhere/');
```
In the file `someTemplate.mdt` you can write all you want. You just need to add the statement below to indicate where to
include the calling template.
```md
[#]: baseInclude
```
Note that you can add this statement as much as you want, it will just include the html at each place.
#### Include template
You can also include another template in your template. For that you just have to write :
```md
[#]: include someTemplate
```
It will then look for the file `someTemplate.mdt` from where the template is located. You can override this by providing
a search path to the library :
```php
$engine->includePath('someWhere');
```
Your include template can get some values from the calling template. For that, you just need to add these values after
the template name :
```md
[#]: include someTemplate { "foo":"bar", "hello":"world" }
```
#### Scripting
You can also create conditions and loops. Let's begin with conditions.
```md
{% if foo == "bar" %}
The variable foo is equal to bar
{% else %}
The variable foo is not equal to bar
{% endif %}
```
The statements `{% %}` needs to have their own line. Conditions work like in php.
And now, loops :
```md
{% for value in values %}
- {value}
{% endfor %}
```
Like for conditions, loop statements needs to have their own line.
### Generate html
Finally, there is how to use the engine to generate html document from a template file :
```php
use Gashmob\MdGen\MdGenEngine;
// Create a new instance of the engine
$engine = new MdGenEngine();
// Set base and include paths
$engine->basePath('bases/');
$engine->includePath('includes/');
// Pre-render template (this is optional)
$array = $engine->preRender('myTemplate.mdt');
/* Compute some values from $array */
// Render template
$html = $engine->render('myTemplate.mdt', [
"foo" => "bar",
]);
```
### Cache
To avoid long render time each time, you can use the internal cache system that store in a dedicated dir the results of past renders. By default this system is disable, but you can enable it by using :
```php
use Gashmob\MdGen\MdGenEngine;
$engine = new MdGenEngine();
// Enable cache
$engine->cache('path/to/cache/dir');
// Disable cache
$engine->cache(false);
```
If the dir doesn't exists, it will create it. When you enable the cache, it will be enable for all instances of `MdGenEngine`.
You can also set the lifespan of cache by using :
```php
use Gashmob\MdGen\MdGenEngine;
MdGenEngine::$cacheLifespan = 3600 * 24 * 365; // 1 year in seconds
```
By default the lifespan is set to 1 month.
## Installation
The easiest way to use this library is to pass from composer with :
```console
composer require gashmob/mdgen
```