https://github.com/polterguy/magic.web.markdown-articles
https://github.com/polterguy/magic.web.markdown-articles
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/polterguy/magic.web.markdown-articles
- Owner: polterguy
- License: mit
- Created: 2022-11-20T13:42:32.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-11-21T05:49:51.000Z (over 3 years ago)
- Last Synced: 2025-02-28T23:02:31.483Z (over 1 year ago)
- Language: HTML
- Homepage: https://ainiro.io
- Size: 28.3 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Markdown article plugin for magic.web
This plugin allows you to easily implement Markdown article support for your dynamically rendered Hyperlambda
websites. Each article is supplied by creating a Markdown file within some folder, with front matter parts
declaring the title of the article, and its content such as follows.
```markdown
---
title: Hello world
---
This is an example article.
1. This is some numbered list
2. This is another list item
This is a [hyperlink](https://aista.com) leading to Aista's website.
```
The plugin contains several _"mixin"_ components that can be used to list articles, get article
content, etc.
## Listing articles
Assuming you have this plugin inside of _"/etc/plugins/magic.web.markdown-articles/"_, and your actual
articles inside of _"/etc/articles/"_ this mixin allows you to render a list of articles in your
installation such as follows.
**/index.hl**
```
.list-articles
io.file.mixin:/etc/plugins/magic.web.markdown-articles/list.html
.root-url:/articles/
.root-folder:/etc/articles/
return:x:-
```
The above **[.root-url]** is the root URL of where you want users to be able to read your articles, and
the above **[.root-folder]** parts is the physical folder on disc where you keep your Markdown files.
The above could be referenced in your HTML such as follows.
**/index.html**
```html
{{*/.list-articles}}
```
The above will return a bulleted list of all articles it can find in your _"/etc/articles/"_ folder.
The **[.root-url]** argument is the root URL of where individual articles can be found. If you for
instance have a file named _"/etc/articles/hello-world.md"_ the above will result in the following
root URL _"/articles/hello-world"_. Below is an example of its output.
```html
```
You can also invoke the list articles mixin with a **[.verbose]** argument with a value of `true`,
at which point the returned HTML will resemble the following.
```html
```
Notice, if you do, your article Markdown files needs to have at least the following front matter
parts declared.
```markdown
---
title: Hello world
excerpt: This is an excerpt
image: https://aista.com/wp-content/uploads/2022/11/twitter-elon.jpg
---
... article content ...
```
## Displaying articles
To actually resolve individual articles, you'll need a _"default.hl"_ file, a _"default.html"_
file, and an _"interceptor.hl"_ file that can be found in whatever **[.root-url]** folder you choose
to render your articles from. Below is an example of all 3 required files.
**/articles/interceptor.hl**
```
/*
* Interceptor for articles, doing all the heavy lifting, actually
* loading articles, by intercepting the main display article Hyperlambda file.
*/
// Executing get-article Hyperlambda file, putting content into [.article] node.
.article
add:x:@.article
io.file.execute:/etc/plugins/magic.web.markdown-articles/get-article.hl
.root-folder:/etc/articles/
// Interceptor node, replaced by default.hl Hyperlambda content.
.interceptor
```
**/articles/default.html**
```
{{@.article/*/title}}
{{@.article/*/title}}
{{@.article/*/content}}
```
**/articles/default.hl**
```
/*
* Since we don't have any logic in our actual article Hyperlambda file,
* this file can be empty, since all the heavy lifting is actually done
* in the interceptor file, and expressions in HTML file are leading
* directly to nodes in our interceptor file.
*
* However, the file still needs to exist on disc, otherwise the endpoint
* resolver will load the file as static content, and never return the file
* as a mixin.
*/
```
The point with the above, is that your interceptor loads the article's content once,
and then adds the semantic content from your Markdown file into its **[.blog]** node,
before the default URL resolver executes, which at that point can reference values
from your blog, such as its content, title, etc. The URL dynamically ends up resolving
to the filename of whatever article the user is requesting. A URL of for
instance _"/articles/foo"_ resolves to the physical file _"/etc/articles/foo.md"_.