DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:xtern

External Link Check

Compatible with DokuWiki

  • 2018-04-22 "Greebo" yes
  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" yes

plugin Checks external links for connection errors, with tools for fixing them

Last updated on
2019-06-24
Provides
Action
Repository
Source

Tagged with icons, links

Installation

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

External requirements

1. This plugin requires the PHP curl library.
2. It also requires valid CA certificate file(s) for ssl. This generally is not a problem on linux systems where openssl has been installed. On Windows these certificates may not be available for use by curl. For Windows and other instances where not available you can install the certificates from the xtern admin panel. Or you can self-install pem certificate files. See:

For this certificate configuration, you must also set to true the ca_required configuration option.

Examples/Usage

Usage

The plugin checks to see if an external url is accessible. If it is, then it will replace the standard gray external link icon with a green globe. If not, it will replace the gray icon with a red globe. This is in keeping with DokuWiki's use of green for valid internal links and red for broken internal links. These changes do not apply to interwiki links. Interwiki links have the class interwiki and have icons specific to the wiki or else the Dokuwiki generic interwiki icon. External links have the class urlextern and get the globe icon.

HTTP Status codes 4xx

A group of http status codes in the 400 range designate urls that are not technically broken but are restricted from accessing their targets. These are marked, as above, with the black and white “explore-off” icon adapted from the Material Design icon collection. On a mouse-over, a tooltip shows the status code and its name.

Command Line Script

There is a script in the scripts directory which can be run from the lib/exe directory:

  php chk_links.php

This will list broken links and the pages where they occur. The command line script has no time limit, and processes the complete wiki.

Admin Panel

You can also run a check in the plugin's administration panel. This is preferable to the script, giving more complete results. Here you can do the check by namespace or for the entire wiki. The output in the admin panel creates links which open a new window ready for editing your broken links. Not all errors show https status codes. Some will show curl error codes with explanations. What shows up here as curl errors, in the normal page display will be marked with the red globe.

Checking the entire wiki on large sites may need more than the max_execution_time set for php scripts on your system. The plugin has a max_time configuration option. This defaults to 120 seconds and can be increased.

The admin panel check saves the list of broken links and their pages. There is a Review button which enables you to re-check your result at a later time using this saved list. It is faster than the original check because it does not have to parse the wiki pages to search for external links. As with the original link check, here too you can open the wiki pages for editing.

Note: To use this feature, you must first run the xtern admin app from the Admin page. It uses the database created by the app. This database should be kept current for this feature to work optimally.

When the new window opens for editing, the broken links for this page will be displayed at the top of the page in yellow message banners. In the file itself, the broken links will be marked as broken:

__ BROKEN-LINK: [[http://www.mturner.org/html/credits.tgz|mturner.org]] LINK-BROKEN __

When the Preview button is clicked these will show up as underlined. Keep in mind that this is a preview. To keep the broken link markup in your page, click the Save button; to discard, click Cancel.

You can also open pages from the the links in the admin panel. The page will open in a new tab or window with the broken link markup in place.

By default, the BROKEN-LINK: . . . LINK-BROKEN markup will be hidden from general viewing if it has been saved to the file, and there will be no underlining. Though it is in the page text, it will be displayed in the browser only in the preview mode. This can be changed by setting the conceal configuration option to false, in which case the broken link markup will display whenever the page is loaded into the browser. The broken link icon is not affected by this setting; it will continue to display until the link is fixed.

You can also use the skip_pages option to conceal the broken link icons on a per page basis.

No Icons

It is possible to use this plugin without displaying its icons for broken, valid, and status 400 links. To do this, set the noicons option to true. This does not affect the check link features of the Administration panel or the BROKEN-LINK:. . .LINK-BROKEN markup.

Configuration Options

Name Description Default
ca_requiredThis wiki uses a cacerts.pem file installed in the xtern/ca directory. See external_requirementsfalse
max_timeTime in seconds to allow for broken link checking in the admin panel. See admin_panel120
concealDisplay BROKEN-LINK markup in preview mode only; hide it for general viewing of pages.true
noiconsDo not display the xtern plugin's link icons in the browser. This does not affect the link checking features of the admin panel.false
alt_divSome templates do not use the default id to identify the div which holds the page content; if yours is one of these, enter the div id here
alt_classSome templates identify the div which holds the page content by a class name; if yours is one of these, enter the class name here
skip_pagesA comma separated list of pages where you want the xtern link icons to be suppressed.

Discussion

Please use the forum or the github issue tracker.

plugin/xtern.txt · Last modified: 2019-06-25 15:59 by turnermm