#format wiki
#language en
#pragma section-numbers off
#acl IanRiley:read,write,delete,revert,admin All:read
#pragma supplementation-page on

<<TableOfContents>>

= AnchorLink =

== Background and rationale ==

MoinMoin provides a the macro `<<Anchor(anchorname)>>` to insert anchors into a page. To link to anchors in the current page the MoinMoin markup is `[[#anchorname]]` or `[[#anchorname|label text]]`. This inserts a link using a call to the `pagelink` function of the formatter, with the link created in the form `<a href="/pagename#achorname">anchorname</a>`. This works fine but it isn't interpreted as a internal page link when converted to a PDF by [[http://code.google.com/p/wkhtmltopdf/|wkhtmltopdf]] as used in the [[PDF.py]] action.

However, the internal page links to title anchors inserted by the `<<TableOfContents>>` macro are interpreted correctly by [[http://code.google.com/p/wkhtmltopdf/|wkhtmltopdf]]. This occurs because `<<TableOfContents>>` calls the `anchorlink` function of the formatter. This function creates a link in the form `<a href="#achorname">anchorname</a>`.

Therefore, a macro to create a link to an anchor in the current page in the same way links are created by the `<<TableOfContents>>` macro is needed to provide compatibility with the [[PDF.py]] action.

== Description ==

!AnchorLink is a macro to insert a link to an anchor in the current page using HTML that is correctly interpreted when the page is converted to a PDF by [[http://code.google.com/p/wkhtmltopdf/|wkhtmltopdf]] as used in the [[PDF.py]] action.

The label text is inserted without a # prefix. This prefix is included for links created by `[[#anchorname]]`, which is ideal. So if the `anchorname` is meaningful in its own right, no alternative text needs to be provide, keeping the markup more readable.

== Usage ==

=== <<AnchorLink(text)>> ===

{{{

<<AnchorLink(anchorname) - inserts anchor link using anchorname as the label text.

<<AnchorLink(anchorname|description>> - inserts anchor link using description as the label text.

}}}

To be functional an anchor must be created by `<<Anchor(anchorname)>>` elsewhere in the page. 

Alternatively `anchorname` can be the same as a heading, thereby creating a link to that heading because MoinMoin creates anchors for all headings.

== Example ==

{{{

<<AnchorLink(ExampleAnchor|Click to go to Example Anchor)>>

<<AnchorLink(Example Heading|Click to go to Example Heading)>>

<<Anchor(ExampleAnchor)>> Example anchor here.

=== Example Heading ===

}}}

<<AnchorLink(ExampleAnchor|Click to go to Example Anchor)>>

<<AnchorLink(Example Heading|Click to go to Example Heading)>>

<<Anchor(ExampleAnchor)>> Example anchor points here.

=== Example Heading ===

Example anchor link point to this section.

== Download & Release Notes ==
|| Download || Release Version || Moin Version || Release Notes ||
|| [[attachment:AnchorLink-1.0.py]] || 1.0 || 1.9.2  ||  ||

== Copyright ==

 . @copyright: 2013 Ian Riley <ian.riley@internode.edu.au>

== License ==

GNU GPL, see COPYING for details.

== Known issues and limitations ==

 * If `<<AnchorLink(anchorname)>>` is used after `<<PageBreak()>>` (see [[PageBreak.py]]), even though [[http://code.google.com/p/wkhtmltopdf/|wkhtmltopdf]] creates a new page in the PDF the anchor link doesn't reliably point to that page. When the new page starts with a heading, an anchor link to that heading seems to be more reliable.

-----

 Hits:: <<Hits>>