lektor-website/plugins/lektor-shortcodes/index.html

287 lines
12 KiB
HTML
Raw Normal View History

2022-02-20 15:15:38 +01:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
2022-12-17 10:12:40 +01:00
<link rel="stylesheet" href="../../static/styles.css?h=dff0aaad">
2022-02-20 15:15:38 +01:00
<link rel="stylesheet" href="../../static/pygments.css">
<link rel="shortcut icon" href="../../static/favicon.png?h=fa09bedd">
<title> | Lektor Static Content Management System</title>
</head>
<body class="default">
<nav class="navbar navbar-inverse navbar-static-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed"
data-toggle="collapse" data-target="#navbar"
aria-expanded="false" aria-controls="navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../../">Lektor</a>
</div>
<div id="navbar" class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li><a href="../../downloads/">Download</a></li>
<li><a href="../../docs/">Documentation</a></li>
<li><a href="../../showcase/">Showcase</a></li>
<li class="active"><a href="../">Plugins</a></li>
<li><a href="../../community/">Community</a></li>
<li><a href="../../blog/">Blog</a></li>
</ul>
</div>
</div>
</nav>
<div class="body-wrapper">
<div class="page-banner page-banner-300" style="background-image: url(../header.jpg)"></div>
<div class="container">
<!-- Place this tag in your head or just before your close body tag. -->
<div class="plugin">
<div class="row">
<div class="col-sm-12">
2023-03-03 04:37:58 +01:00
<h1>Plugin &ndash; lektor-shortcodes 0.2.7</h1>
2022-02-20 15:15:38 +01:00
</div>
</div>
<div class="row">
<div class="col-sm-1"></div>
<div class="col-sm-11">
<p>Allows you to use shortcodes (something like tags) in your model fields.<p>
</div>
</div>
<div class="row">
<div class="col-sm-3 plugin-margin">
<h4>Project links</h4>
<ul class="tree-nav">
<li><a href="https://github.com/skorokithakis/lektor-shortcodes" class="ext">Homepage</a></li>
</ul>
<div class="separator">
<h4>GitHub Statistics</h4>
</div>
<ul class="button-nav">
<li><p><a class="github-button" href="https://github.com/skorokithakis/lektor-shortcodes" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star lektor-shortcodes on GitHub" target="_blank">Star</a></p></li>
<li><p><a class="github-button" href="https://github.com/skorokithakis/lektor-shortcodes/fork" data-icon="octicon-repo-forked" data-show-count="true" data-size="large" data-show="true" aria-label="Open Issues" target="_blank">Fork</a></p></li>
<li><p><a class="github-button" href="https://github.com/skorokithakis/lektor-shortcodes/issues" data-icon="octicon-issue-opened" data-show-count="true" data-size="large" data-show="true" aria-label="Open Issues" target="_blank">Open Issues</a></p></li>
</ul>
<div class="separator">
<h4>Meta</h4>
</div>
2023-03-03 04:37:58 +01:00
<p><strong>Version:</strong> 0.2.7</p>
2022-02-20 15:15:38 +01:00
<p><strong>Author:</strong>
2022-09-13 16:42:43 +02:00
<a href="mailto:hi@stavros.io">Stavros Korokithakis,,,</a>
2022-02-20 15:15:38 +01:00
</p>
<div class="separator">
<h4>Tags</h4>
</div>
<a href="../tag/Jinja-filters/">Jinja filters</a>,
<a href="../tag/Markdown/">Markdown</a>,
<a href="../tag/markdown-config/">markdown-config</a>,
<a href="../tag/setup-env/">setup-env</a>,
and
<a href="../tag/shortcodes/">shortcodes</a>
2022-02-24 02:43:35 +01:00
<p>
View <a href="../tags/" class="ref">all tags</a>.
</p>
2022-02-20 15:15:38 +01:00
</div>
<div class="col-sm-9 doc-styling">
<h2>Project Description</h2>
2023-03-03 04:37:58 +01:00
<h1>Lektor Shortcodes</h1>
<p><a href="https://pypi.python.org/pypi/lektor-shortcodes" rel="nofollow"><img src="https://img.shields.io/pypi/v/lektor-shortcodes.svg" alt="PyPI"></a></p>
<p>The Lektor Shortcodes plugin allows you to use shortcodes (shortcodes are
something like custom tags) in your fields (not templates), so your content
doesn't have to have repetitive snippets over and over.</p>
<p>For example, my blog has some specific HTML that I add when I want an image with
a border and caption to be displayed. The HTML looks like this:</p>
<pre lang="html"> <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;alignright&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;image-large.jpg&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">img</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;image.jpg&quot;</span> <span class="p">/&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;caption&quot;</span><span class="p">&gt;</span>The caption<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
</pre>
<p>Copy-pasting this every time gets tedious, and I have to search and replace it
in all the content files every time I want to make a change. With the
shortcodes plugin, this can be written as:</p>
<pre><code>[% image align=right link=&quot;image-large.jpg&quot; image=image.jpg caption=&quot;The caption&quot; %]
</code></pre>
<p>Much easier, cleaner and less repetitive.</p>
<h2>Installation</h2>
<p>To install the plugin, just add <code>lektor-shortcodes</code> to your plugins from the
command line:</p>
<pre><code>lektor plugins add lektor-shortcodes
</code></pre>
<h2>Usage</h2>
<p>Using the plugin is simple. Just create a config file called <code>shortcodes.ini</code> in
your <code>configs</code> directory and specify some shortcode templates. The templates are
full Jinja templates, although (due to some limitations of ini files) they need
to be on one line.</p>
<p>For instance, for the example above, the config file could be:</p>
<pre lang="ini"><span class="k">[global]</span>
<span class="na">image</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#39;&lt;div class=&quot;align{{ align }}&quot;&gt;{% if link %}&lt;a href=&quot;{{ link }}&quot;{% if not link.startswith(&quot;http&quot;) %} data-lightbox=&quot;gallery&quot;{% endif %}&gt;{% endif %}&lt;img src=&quot;{{ image }}&quot;&gt;{% if link %}&lt;/a&gt;{% endif %}{% if caption %}&lt;span class=&quot;caption&quot;&gt;{{ caption }}&lt;/span&gt;{% endif %}&lt;/div&gt;&#39;</span>
</pre>
<p>This will allow you to use shortcodes with optional arguments, like so:</p>
<pre><code># An image with no caption or link:
[% image align=right image=hello.jpg %]
# An image with a link:
[% image align=right link=http://www.example.com image=hello.jpg %]
# Link and caption:
[% image align=right link=http://www.example.com image=hello.jpg caption=&quot;Hello!&quot; %]
</code></pre>
<p>Shortcodes defined within the section named <code>global</code> will be processed
automatically inside any of your sites Markdown content. It is also possible to
define shortcodes which are only expanded when the Jinja2 template for a page
explicitly requests it. Shortcodes defined in any section not named <code>global</code>
will only be applied when the template passed the content through a Jinja2
filter named <code>shortcode</code>. For example, if your HTML template references a field
called <code>body</code>, and your config has a section called <code>[special]</code>, you may request
expanding shortcodes defined within the <code>special</code> section like so:</p>
<pre><code>{{ body|shortcodes(section=&quot;special&quot;) }}
</code></pre>
<p>This will enable all shortcodes from the specified section, in addition to all
globally defined shortcodes. If no section is specified, the filter defaults to
the section named <code>main</code> (so it will include shortcodes in <code>main</code> unless you
request a different section, and it will always include shortcodes in <code>global</code> no
matter what).</p>
<h2>Miscellanea</h2>
<p>If you find a bug or have a feature request, please open an issue or file a PR.
Thanks!</p>
2022-02-20 15:15:38 +01:00
<div class="comment-box">
<h2>Comments</h2>
<div id="disqus_thread"></div>
<script>
var disqus_config = function() { this.page.identifier = "/plugins/lektor-shortcodes"; this.page.url = "https://www.getlektor.com/plugins/lektor-shortcodes/"; };
(function() {
var d = document, s = d.createElement('script');
s.src = '//lektordocumentation.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>
Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript"
rel="nofollow">comments powered by Disqus.</a>
</noscript>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="bottomsummary">
<div class="container">
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-sm-4 icon-bar">
<a href="https://github.com/lektor/lektor/" title="Lektor on GitHub"
><i class="fa fa-github"></i></a>
<a href="https://github.com/lektor/lektor/issues/" title="Report Issues for Lektor"
><i class="fa fa-bug"></i></a>
<a href="https://twitter.com/getlektor" title="Find Lektor on Twitter"
><i class="fa fa-twitter"></i></a>
<a href="https://gitter.im/lektor/lektor" title="Chat on Gitter"
><i class="fa fa-comment"></i></a>
<a href="https://github.com/lektor/lektor-website/tree/master/content/plugins/lektor-shortcodes/contents.lr" title="View source for this page"><i class="fa fa-code"></i></a>
</div>
<div class="col-sm-8">
<a href="../../license/">License & Copyright</a>
<a href="../../contact/">Contact</a>
Made with <i class="fa fa-fw fa-heart" title="Heart"><span hidden>Heart</span></i> in Carinthia
</div>
</div>
</div>
</footer>
2023-07-19 20:30:41 +02:00
<script type=text/javascript src="../../static/app.js?h=8b801996" charset="utf-8"></script>
2022-02-20 15:15:38 +01:00
<script>
((window.gitter = {}).chat = {}).options = {
room: 'lektor/lektor',
activationElement: null
};
document.write('<button class="js-gitter-toggle-chat-button">Toggle Chat</button>');
var dnt = navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack;
if (dnt != "1" && dnt != "yes") {
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-70822533-1', 'auto');
ga('set', 'anonymizeIp', true);
ga('send', 'pageview');
} else {
console.debug("Respecting Do-Not-Track, not running analytics.");
}
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>
<script async defer id="github-bjs" src="https://buttons.github.io/buttons.js"></script>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>
</body>
</html>