README
metalsmith-href
A Metalsmith plugin to insert files URL in metadata
This plugin inserts absolute URLs to files in the metadata. This is useful to fill href
attributes in templates. Used with metalsmith-link, it is possible to create links between files without having to worry about their location in the destination folder.
Getting started
- Install this plugin (see Installing)
- Add it to your Metalsmith build file or configuration
- Use the
href
property in your templates (see examples below) - (optional) customize the name of the
href
property (see Configuring)
Example layout
See metalsmith-link to fill the links
property.
<!DOCTYPE html>
<html>
<head>
<title>{{ title }}</title>
</head>
<body>
<header>
<h1>{{ title }}</h1>
</header>
<nav>
<ul>
<li><a href="{{ href }}">Useless link to this page</a></li>
{% for link in links %}
<li><a href="{{ link.href }}">{{ link.title }}</a></li>
{% endfor %}
</ul>
</nav>
<main>
{{ contents | safe }}
</main>
<footer>
<hr />
Licensed under CC-BY-SA
</footer>
</body>
</html>
Installing
With npm installed, run
$ npm install metalsmith-href
For static websites, some prefer to specificy --save-dev
to npm install
as the distributed website does not actually require this plugin as a dependency.
Configuring
Since Metalsmith follows a Pipeline pattern, the step at which plugins run is important. This plugin should ideally run just before the layout step.
There are a few options:
name | default | description |
---|---|---|
property | href | name of the metadata property to create/replace |
basehref | empty | base URL to preprend (e.g. https://my-site.tld) |
index | index.html | name of the directory index file to strip (e.g. for links like / instead of /index.html ) |
Example build file with options
// ...
Metalsmith(__dirname)
.use(link())
.use(markdown())
.use(href({ property: "url", basehref: "https://my-site.tld", index: "index.htm" }))
.use(layouts())
.build(function (err) {
if (err) throw err;
});
Example configuration with options
{
"source": "src",
"destination": "build",
"plugins": [{
"metalsmith-link": {},
"metalsmith-markdown": {},
"metalsmith-href": {
"property": "url",
"basehref": "https://my-site.tld",
"index": "index.htm"
},
"metalsmith-layouts": {}
}]
}
Contributing
If you'd like to contribute, please fork the repository and use a feature branch. Issues and pull requests are warmly welcome.
Links and references
- Source code:
https://github.com/pierresenechal/metalsmith-href
- Issue tracker:
https://github.com/pierresenechal/metalsmith-href/issues
Related
- Metalsmith Link:
https://github.com/pierresenechal/metalsmith-link
Dependencies
- Metalsmith:
https://github.com/segmentio/metalsmith
License
This software is free software licensed under the MIT License. See LICENSE.MD