Description: Shortcodes are shorthand to make managing content easier. They can be used in content or templates. Shortcodes are shorthand to make managing content easier. They can be used in content or templates. In content they are as follows.
<sc>figure('A bald eagle observes', 'Eagle', '/assets/images/eagle.jpg')</sc>
Or they can be used in templates like so. <% f = site.shortcodes['figure'](site, page, 'A bald eagle observes', 'Eagle', '/assets/images/eagle.jpg') %> ${f} The shortcode `figure` will generate the following HTML.
Eagle
A bald eagle observes
Which looks like this: figure('A bald eagle observes', 'Eagle', '/assets/images/eagle-150x200.jpg') ## Creating new shortcodes Shortcodes are Python functions(def) defined in `shortcodes.py`, in the site root directory. Shortcode functions must: - Accept at least site and page objects as arguments e.g `def my_sc(site, page[, any other arguments])` - Return a string The figure shortcode above could be written in `shortcodes.py` as follows. Remember that all shortcode functions must accept site and page arguments. def figure(site, page, caption, alternative_text, src_path): html = '
\n' html += '' + alternative_text + '\n' html += '
' + caption + '
\n' html += '
\n' return html ## Site and page Most shortcodes will want access to either the site or page attributes that Pagegen creates. To give a shortcode access to them, they are automatically passed to the shortcode function. This happens automatically from the <sc> tag, but need to be explicitly used when calling shortcodes in the templates. These variables are automatically available in all templates. The trade off to this inconsistency, between <sc> tag and template arguments, is to keep the tags more succinct. ## Return Markdoen of reStructuredText? Shortcodes are run before the page is converted to html, meaning the shortcode return value is evaluated as either Markdown or reStructuredText, dependant on the page markup header. Therefore shortcodes need to return strings that are compatible with the markup engine that will process them further. The example above will work with Markdown, but to make it compatible with reStructuredText additional markup needs to be added. def figure(site, page, caption, alternative_text, src_path): html = '.. raw:: html\n\n' html = '
\n' html += ' ' + alternative_text + '\n' html += '
' + caption + '
\n' html += '
\n' return html ## Shortcodes to handle the different markups The figure shortcode example can be updated to use the page object to determine if it should return markup for Markdown or reStructuredText. def figure(site, page, caption, alternative_text, src_path): if page.markup == 'rst': html_prefix = '.. raw:: html\n\n\t' indent = '\t' else: # Markdown html_prefix = '' indent = '' html = html_prefix + '
\n' html += indent + '' + alternative_text + '\n' html += indent + '
' + caption + '
\n' html += indent + '
\n' return html ## Built in shortcodes Pagegen ships with ready to use built in shortcodes. Built in shortcodes will be overridden if a shortcode defined in `shortcodes.py` has the same name. !!! Note When using <sc> tag, omit the site and page arguments, they get passed automatically. For instance, use <sc>tags()</sc> to call the tags shortcode, no need to specify site and page, they are passed implicitly. list_shortcodes() In addition `pgn --init` will include `shortcodes.py_example` to illustrate further.