Some time ago, browsing the Grav forum I noticed that a user objects that the external files handled by the Markdown sections plugin, were not usable with the Admin interface.

I don't like the Admin interface, because I prefer to work directly on markdown files so I don't feel that as a problem, but that's me and I must admit that user was right. I started to look for something that can give me the chance to handle Gravstrap components using another approach, but, in general, something that can replace Markdown sections, and I met shortcodes.

A shortcode is a kind of small script-like text fragment, that can be added directly to a markdown page. Grav already provides two plugins that handle shortcodes: the shortcode-core and and shortcode-ui plugins.

The first one takes care to provide core functionalities for handling shortcodes and implements some tiny shortcodes by itself. The second one depends on core and implements more complex shortcodes, like tabs, callouts, images compare and more.

That was the right tool for me. I dug into those plugins' code to understand how they work, next I made Gravstrap capable to manage all the implemented Bootstrap components with shortcodes.

Let's see some examples. Here it is the shortcode that handles the Bootstrap navbar you can add it to any of your web site markdown page:

[g-navbar id=navbar name=navbar fixed=top centering=none brand_text="Brand"]
    [g-navbar-menu alignment="center"][/g-navbar-menu]    
    [g-navbar-menu icon_type="fontawesome" alignment="right" attributes="class:social-menu"]
        [g-link url="https://twitter.com/giansi72" icon="twitter"][/g-link]
        [g-link url="https://www.facebook.com/diblas.net" icon="facebook"][/g-link]
        [g-link url="https://github.com/giansi" icon="github"][/g-link]
        [g-link url="http://www.stumbleupon.com/stumbler/Giansimon" icon="stumbleupon"][/g-link]
        [g-link url="http://feeds.feedburner.com/diblas" icon="rss"][/g-link]
    [/g-navbar-menu]
[/g-navbar]

That's clean and easy to implement. But that's not enough. You can configure the shortcode not to be rendered, just adding the render=false parameter. In this case the parsed output is assigned to a twig variable named as the shortcode id, which can be used everywhere in your template.

[g-navbar id=navbar name=navbar fixed=top centering=none brand_text="Brand"]
    [g-navbar-menu alignment="center"][/g-navbar-menu]    
    [g-navbar-menu icon_type="fontawesome" alignment="right" attributes="class:social-menu"]
        [g-link url="https://twitter.com/giansi72" icon="twitter"][/g-link]
        [g-link url="https://www.facebook.com/diblas.net" icon="facebook"][/g-link]
        [g-link url="https://github.com/giansi" icon="github"][/g-link]
        [g-link url="http://www.stumbleupon.com/stumbler/Giansimon" icon="stumbleupon"][/g-link]
        [g-link url="http://feeds.feedburner.com/diblas" icon="rss"][/g-link]
    [/g-navbar-menu]
[/g-navbar]

and then in your twig template:

{{ navbar1 }}

A navbar is a component which is rendered on each page of the web site. Grav does not provide a place where you can add contents shared between pages. To solve this issue, the plugin looks for a special page called common which will contain all the common components you need to share between the pages of your web site. This page must be set as hidden, so it is implemented as follows:

# common/default.md
---
visible: false
---

[g-navbar id=navbar name=navbar fixed=top centering=none brand_text="Brand" render=false]
    [g-navbar-menu alignment="center"][/g-navbar-menu]    
    [g-navbar-menu icon_type="fontawesome" alignment="right" attributes="class:social-menu"]
        [g-link url="https://twitter.com/giansi72" icon="twitter"][/g-link]
        [g-link url="https://www.facebook.com/diblas.net" icon="facebook"][/g-link]
        [g-link url="https://github.com/giansi" icon="github"][/g-link]
        [g-link url="http://www.stumbleupon.com/stumbler/Giansimon" icon="stumbleupon"][/g-link]
        [g-link url="http://feeds.feedburner.com/diblas" icon="rss"][/g-link]
    [/g-navbar-menu]
[/g-navbar]    

As bonus, I have implemented several modules as shortcodes. For example here it is the web site footer defined as a shortcode, which usually will be added to common page:

# common/default.md

[g-footer-two name="footer" render=false]
[g-section name="credits"]

This website is made with [Grav CMS](http://getgrav.org/) and it is powerd by [Gravstrap Theme](http://diblas.net/themes/gravstrap-theme-to-start-grav-cms-site-with-bootstrap-support/) and [Gravstrap Plugin](http://diblas.net/plugins/use-bootstrap-elements-in-the-grav-cms-way/)

[/g-section]

[g-section name="copyright"]Joe Bloggs[/g-section]
[g-section name="license"]The whole documentation in this site is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported [License](http://creativecommons.org/licenses/by-sa/4.0/)[/g-section]

[/g-footer-two]

Another example is the portfolio module, which also uses the bootstrap thumbails component:

[g-portfolio name=_portfolio attributes="class:portfolio module"]

## Showcase your work
Use the `Portfolio module` to spread your works to the world

___

[g-thumbnail]
[g-thumbnail-item image="coffee.jpg" url="http://diblas.net"][/g-thumbnail-item]
[g-thumbnail-item image="farmerboy.jpg" url="http://diblas.net"][/g-thumbnail-item]
[g-thumbnail-item image="girl.jpg" url="http://diblas.net"][/g-thumbnail-item]
[g-thumbnail-item image="judah.jpg" url="http://diblas.net"][/g-thumbnail-item]
[g-thumbnail-item image="origami.jpg" url="http://diblas.net"][/g-thumbnail-item]
[g-thumbnail-item image="retrocam.jpg" url="http://diblas.net"][/g-thumbnail-item]
[/g-thumbnail]

[/g-portfolio]

What do you think about this new approach? Let me know in comments below.

Please take note that this plugin introduces a compatibility break with previous 0.9.x release, so do not immediately upgrade a web site in production.

At last due to these changes, the Markdown Sections plugin is deprecated and is not maintained anymore.

Previous Post

Related Posts