2021-06-21 06:33:18 +00:00
# Angel3 Markdown
2017-08-13 04:24:38 +00:00
2022-01-04 12:03:52 +00:00
2021-06-21 06:33:18 +00:00
[](https://dart.dev/null-safety)
2024-07-07 15:02:49 +00:00
[](https://discord.gg/3X6bxTUdCM)
2023-12-25 03:45:10 +00:00
[](https://github.com/dart-backend/angel/tree/master/packages/markdown/LICENSE)
2021-06-21 06:33:18 +00:00
Markdown view generator for Angel3.
With this plug-in, you can easily serve static sites without doing more than writing simple Markdown. Thus, it is a friendly choice for writing API documentation or other tedious HTML-writing tasks.
## Installation
2017-08-13 04:24:38 +00:00
In your `pubspec.yaml` :
```yaml
dependencies:
2023-12-24 16:10:10 +00:00
angel3_framework: ^8.0.0
angel3_markdown: ^8.0.0
2017-08-13 04:24:38 +00:00
```
2021-06-21 06:33:18 +00:00
## Usage
It's very straightforward to configure an Angel server to use Markdown. Keep in mind to use `package:file` instead of `dart:io` :
2017-08-13 04:24:38 +00:00
```dart
configureServer(Angel app) async {
2019-04-11 16:19:12 +00:00
var fs = LocalFileSystem();
2017-08-13 04:24:38 +00:00
await app.configure(markdown(
// The directory where your views are located.
2019-04-11 16:19:12 +00:00
fs.directory('views'),
2017-08-13 04:24:38 +00:00
));
}
```
2023-12-24 16:10:10 +00:00
You can then generate HTML on-the-fly in a request handler. Assuming your view directory contained a file named `hello.md` , the following would render it as an HTML response:
2017-08-13 04:24:38 +00:00
```dart
configureServer(Angel app) async {
app.get('/hello', (res) => res.render('hello'));
}
```
2021-06-21 06:33:18 +00:00
`package:angel3_markdown` by default searches for files with a `.md` extension; however,
2017-08-13 04:24:38 +00:00
you can easily override this.
## Interpolation
2021-06-21 06:33:18 +00:00
2023-12-24 16:10:10 +00:00
`angel3_markdown` can interpolate the values of data from `locals` before building the Markdown. For example, with the following template `species.md` :
2017-08-13 04:24:38 +00:00
```markdown
# Species: {{species.name}}
The species *{{species.genus.name}} {{species.name}}* is fascinating...
```
You can render as follows:
```dart
requestHandler(ResponseContext res) {
return res.render('species', {
'species': new Species('sapiens', genius: 'homo')
});
}
```
To disable interpolation for a single bracket, prefix it with an `@` , ex: `@{{raw | not_interpolated | angular}}` .
## Templates
2021-06-21 06:33:18 +00:00
2017-08-13 04:24:38 +00:00
Markdown is frequently used to build the *content* of sites, but not the templates.
You might want to wrap the content of pages in a custom template to apply pretty
CSS and JS, etc:
```dart
configureServer(Angel app) async {
await app.configure(
markdown(
// The directory where your views are located.
2019-04-11 16:19:12 +00:00
fs.directory('views'), template: (content, Map locals) {
2017-08-13 04:24:38 +00:00
return '''<!DOCTYPE html>
< html >
< head >
< title > ${locals['title']} - My Site< / title >
< / head >
< body >
$content
< / body >
< / html >
''';
}),
);
}
```
2023-12-24 16:10:10 +00:00
The `template` function will have access to whatever values were passed to the renderer, or an empty `Map` .
2017-08-13 04:24:38 +00:00
## Enhancing Markdown
2021-06-21 06:33:18 +00:00
2023-12-24 16:10:10 +00:00
You can pass an `extensionSet` to add additional features to the Markdown renderer. By default, this plug-in configures it to enable Github-flavored Markdown.
