====== Anchor Plugin ======

---- plugin ----
description: Add HTML anchors to a page. Useful when section headers are really long
author     : Eli Fenton
email      : elifenton@this_is_not_a_real_email.fake
type       : syntax
lastupdate : 2024-02-10
compatible : 2010-11-07, 2011-05-25, Angua, Weatherwax, Binky, Ponder Stibbons, Hrun, Detritus, Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum, Kaos
depends    : 
conflicts  : 
similar    : bookmark,wrap
tags       : anchor, bookmark, links

downloadurl: https://github.com/zioth/dokuwiki-anchor/zipball/master
bugtracker : https://github.com/zioth/dokuwiki-anchor/issues
sourcerepo : https://github.com/zioth/dokuwiki-anchor
donationurl: 
screenshot_img: 
----

DokuWiki allows you to create links to pages, and to section headers. This plugin allows you to link to any arbitrary point in a page.

This plugin is extremely simple, so it's a good place to start if you're trying to figure out how to create a syntax plugin.

===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.


===== Examples/Usage =====

This syntax creates an anchor. Put it anywhere in your page, and links will automatically scroll to that point.

<code>
{{anchor:anchor_name:text}}
</code>

**anchor_name** is an arbitrary name of your choosing. It must begin with a letter, and must be lowercase.

**text**, if provided, is a block of text that the anchor will wrap in HTML. It's not all that useful, unless your template adds space or other decoration to empty anchor tags. It's also optional, so this is also valid:

<code>
{{anchor:anchor_name}}
</code>

To link to an anchor from within DokuWiki:

Use standard DokuWiki syntax to link to the new anchor:

<code>
[[namespace:page_name#anchor_name]]
</code>

To link to an anchor from outside DokuWiki:

<code>
http://server.com/doku/doku.php?id=page_name#anchor_name
</code>

==== Changelog ====

  * 2017-06-20 -- Changed signature of methods ''handle'' and ''render'' to suppress warnings in PHP 7.1.
  * 2013-05-23 -- Integrated changes made by Peter B to fix escaping vulnerability and paragraph formatting.

===== Discussion =====

==== Gratuitous newline ====

The plugin inserts an unwanted newline after the anchor tag. But I want to create a glossary page with anchored entries of the form:\\
**term** -- definition

It looks like the [[:plugin:bookmark|Bookmark]] plugin will serve my purpose.
==== Case sensitivity is not compatible with DW ====
While using anchor I found that you have to type the anchor_name in all lowercase letters to be compatible with the DW internal link mechanics, which converts the letters of a link to lowercase.
To enable copy&paste of anchor names from other text-parts, it would be more convenient if the plugin did that itself.

==== Jumps to top of the page ====
I put an anchor at the bottom of a page.\\ 
If I use this internal link, DW jumps to the top of the page.\\ 
Isn't it possible to jump to the part of the page, where the anchor is defined?<sub>//27.08.2013, Joe//</sub>

Answer: It's possible that your DokuWiki template includes code that automatically scrolls to the top of the page after page load. You can confirm this by creating a link to a Doku section header and seeing if it behaves the same way.

==== /exe/fetch... ====
I created the plugin files and tried to create a link.\\
Instead of creating an anchor is makes a link to /lib/exe/fetch.php?media=anchor:anchor_name:text\\
What am I doing wrong?\\
**EDIT:** My bad, I was using the syntax incorrectly! :) Great work!\\
//2013/11/03/ 01:56// Stephen V

==== Abbreviated use in page ====
Just to tell that it works fine and mostly to tell that even the short notation for the anchor works. \\
This makes the anchors within the page independent of the source page. \\
example: ''%%[[#anchorName|text]]%%'' \\
Great!! \\
//ViForEver 20140207//

==== Needs the colon even with no text ====
Note that even if you don't provide the optional text for the anchor you still need the colon following the anchor name, otherwise the plugin will error.

UPDATE: This has been fixed (2023-08-14)

Very handy little plugin!
//2023/06/30 jon p// 

===== Old Discussion =====

[[plugin:anchor:olddiscussion]]