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.

<div class="pre-lookalike">&lt;sc&gt;figure('A bald eagle observes', 'Eagle', '/assets/images/eagle.jpg')&lt;/sc&gt;</div>

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.

	<figure>
	<img src="/assets/images/eagle.jpg" alt="Eagle">
	<figcaption>A bald eagle observes</figcaption>
	</figure>

Which looks like this:

<sc>figure('A bald eagle observes', 'Eagle', '/assets/images/eagle-150x200.jpg')</sc>


## 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 = '<figure>\n'
		html += '<img src="' + src_path + '" alt="' + alternative_text + '">\n'
		html += '<figcaption>' + caption + '</figcaption>\n'
		html += '</figure>\n'
	
		return html


## Site and page

Most shortcodes will want access to either the <a href="<sc>page_url('/user-manual/site-and-page-attributes')</sc>">site or page attributes</a> that Pagegen creates. To give a shortcode access to them, they are automatically passed to the shortcode function. This happens automatically from the &lt;sc&gt; 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 &lt;sc&gt; 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 = '	<figure>\n'
		html += '	<img src="' + src_path + '" alt="' + alternative_text + '">\n'
		html += '	<figcaption>' + caption + '</figcaption>\n'
		html += '	</figure>\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 + '<figure>\n'
		html += indent + '<img src="' + src_path + '" alt="' + alternative_text + '">\n'
		html += indent + '<figcaption>' + caption + '</figcaption>\n'
		html += indent + '</figure>\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 &lt;sc&gt; tag, omit the site and page arguments, they get passed automatically. For instance, use <code>&lt;sc&gt;tags()&lt;/sc&gt;</code> to call the tags shortcode, no need to specify site and page, they are passed implicitly.

<sc>list_shortcodes()</sc>

In addition `pgn --init` will include `shortcodes.py_example` to illustrate further.