Contribute Your Knowledge ~ Edit Links and Media

FIXME decision needed about where advance material should sit.

Introduction

This section explains how to:

  • create hyperlinks that lead to other pages within the Knowledge Base or to other resources on the Internet
  • embed images within Knowledge Base pages (uploading them first if necessary), and optionally link them to other pages
  • upload other types of files and make them available for download
  • manage uploaded images and other files

The concepts of hyperlinks, images and downloadable files will be familiar to anyone who makes use of the Internet, including this Knowledge Base or FHUG.

The earliest sections explain the basic features, and the later sections need little more expertise.

The simplest way to create an internal link is to use the Internal Link button on the Quick Buttons toolbar. When clicked, it opens the Link Wizard to allow you to choose the namespace and page required, and then creates a link to the chosen page. If you already have some text selected when you click the Internal Link button, that text is shown as link text; if you do not specify link text, the page name is displayed.

The result (which you can also enter directly) is the destination enclosed within square brackets either as just the pagename or with link text.

The result (which you can also enter directly) is the destination enclosed within square brackets,
either as just the [[namespace:pagename]] or with link text [[namespace:pagename|link text]]. 

If you don't specify the namespace, the destination defaults to the same namespace as the page being edited.

To link to a specific section within a page (known as bookmarking), add the section headline behind a hash character. This links to this subsection.

This links to [[Edit Links and Media#Links within the Knowledge Base|this subsection]].

Notes:

  • Links to existing pages are shown in a different style from nonexistent ones. If the destination does not exist, you should either correct the link to point to the right place or use the newly-created link to create a new page.
  • When a section's headline is changed, its bookmark must be changed too, so don't rely on section linking too much.

Namespace Conventions

Namespaces within an internal link are either absolute, or they are relative to the current namespace and thus allow a cluster of pages in a namespace to be moved without needing to edit any links.

It is advised that absolute links use a : prefix, and relative links have no prefix or use a .: or ..: prefix as shown below. See https://www.dokuwiki.org/namespaces for full details of all the alternative formats.

Advised Absolute Link Formats
:page0 Page page0 is in the root namespace
:wiki:ns1:page1 Page page1 is in the ns1 namespace within wiki in the root namespace
:wiki:ns1:ns:page2 Page page2 is in ns within ns1 within wiki in the root namespace
:wiki:ns2:page3 Page page3 is in the ns2 namespace within wiki in the root namespace
Advised Relative Link Formats Equivalent to last three above with a current namespace of :wiki:ns1
page1 Page page1 is in the current namespace i.e. :wiki:ns1:page1
.:ns:page2 Page page2 is in ns within current namespace i.e. :wiki:ns1:ns:page2
..:ns2:page3 Page page3 is in ns2 within parent namespace i.e. :wiki:ns2:page3

The simplest way to create an external link is to use the External Link button on the Quick Buttons toolbar. When clicked, it opens the External Link wizard, which enters a template for creating an external link:

[[http://example.com|External Link]]

You should edit the url to be the link that you want, and also edit the link text, for example This Link points to Google.

[[https://www.google.co.uk|This Link points to Google]].

If you do not need link text, you can enter an external link directly and it will be recognized: https://www.google.co.uk or simply www.google.co.uk.

If you do not need link text, you can enter an external link directly and it will be recognized:
https://www.google.co.uk or simply www.google.co.uk. 

If you're creating the link manually and want link text, you must use the square brackets syntax.

Notes:

  • If a chosen external destination does not exist, the appearance of the link will not change, so you should double-check that you have linked to the correct place when creating these external links.

Email Addresses

E-mail addresses entered like this: andi@splitbrain.org or Jane Taubman are recognised as such automatically.

E-mail addresses entered like this: <andi@splitbrain.org> or 
[[mailto:janetaubman@gmail.com|Jane Taubman]] are recognised as such automatically.

There are a number of shortcuts available to create external links to frequently referenced resources.

These are shortcuts to create links from the Knowledge Base to external resources associated with Family Historian.

Shortcut Site URL and Example
FHUG Forum [[forum>f=code​]] https://​www.fhug.org.uk/​forum/viewforum.php?
​f=code in URL [[forum>f=32]] ⇒ f=32General Usage
FHUG Topic [[topic>t=code​]] https://​www.fhug.org.uk/forum/​viewtopic.php?
​t=code in URL [[topic>t=15916]] ⇒ t=15916Privacy Policy
fh Website [[fhcalico>page]] https://www.family-historian.co.uk/
page is a web page [[fhcalico>features]] ⇒ features
FHU Mail Archive [[fhulist>yyyy/mm/]] https://lists.rootsweb.com/hyperkitty/list/family-historian-users.rootsweb.com
year/month number [[fhulist>2006/10/]] ⇒ Oct 2006 Archive
and [[fhulist>thread/code/]]
thread code number [[fhulist>thread/6104791/]] ⇒ Format

These are shortcuts to create links from the Knowledge Base to other frequently used external resources.

Shortcut Site URL Example with Icon
[[amazon>book ANA or ISBN]]
Amazon ANA or ISBN number
http://www.amazon.co.uk/ [[amazon>0750935103]] ⇒
"Ancestral Trails" by Mark Herber
[[google>search term]] https://www.google.com/search [[google>weather]] ⇒ weather
[[wp>search term]] https://en.wikipedia.org/wiki/ [[wp>genealogy]] ⇒ genealogy
[[wpmeta>search term]] https://meta.wikipedia.org/wiki/ [[wpmeta>genealogy]] ⇒ genealogy
[[doku>wiki topic]] https://www.dokuwiki.org/ [[doku>toolbar]] ⇒ toolbar

It is helpful to users of the Knowledge Base to identify the pages which link back to the page they're reading (Backlinks) and to construct Alphabetic Titles for a Namespace. Both these are supported using plugins.

The Backlinks Plugin allows the Wiki to show all pages which link to the current page if used as follows. See also the Control Macros guide.

List of pages which refer to this one

=== Related Pages ===
{{backlinks>.}}

There are other options for showing backlinks for a different page. See http://www.dokuwiki.org/plugin:backlinks2 for more information.

Syntax: {{backlinks>[namespace:][pagename]}}

Alphabetic Titles

The Alphaindex Plugin supports alphabetic indexes for any namespace headline titles. See also the Control Macros guide.

e.g. Knowledge Base Titles

~~NOCACHE~~
{{alphaindex>|nons}}

e.g. Contribute Your Knowledge Alphabetic Titles

~~NOCACHE~~
{{alphaindex>ContributeYourKnowledge|nons}}

Syntax: {{alphaindex>[namespace][#n][|nons]}}

On any page, you can include internal images (images stored in a namespace within the Knowledge Base) or external images (images from other websites).

Internal Images

To simplest way to embed an image within a page is to use the Add Images and Other Files button on the Quick Buttons toolbar. When clicked, it opens the Media Files Window to allow you to choose the image namespace and file required, together with options for:

  • sizing the image
  • aligning the image
  • linking from the image

before you insert the image.

See Media Files Window for information on how to upload a new image, if the image you want is not already available.

The result (which you can also enter directly) is the image file details and options enclosed in curly brackets:

{{namespace:filename.ext?width x height|caption}}

The namespace follows the Namespace Conventions above.

Notes:

  • If you specify a filename (internal or external) that is not an image file type (gif, jpeg, png), then it will be displayed as a simple hyperlink instead.

External Images

To embed an external image, enclose the image URL in curly brackets. As for internal images, you can resize, align and caption the image, and link it to another page or URL.

Resized external image with caption: Google logo

Resized external image with caption:
 {{https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png?200x50|Google logo}}

Sizing an Image

You can use the standard sizes offered by the Media Files Window, or specify exactly what you want. For example:

Real size:

Resize to given width:

Resize to given width and height:

Real size:                        {{wiki:dokuwiki-128.png}}
Resize to given width:            {{wiki:dokuwiki-128.png?50}}
Resize to given width and height: {{wiki:dokuwiki-128.png?200x50}}

Notes:

  • When the aspect ratio of the given width and height doesn't match that of the image, it will be cropped to the new ratio before resizing.

Aligning an Image

The Media Files Window offers the option to align the image left, right, centred, or not to align it at all, which defaults to left alignment. You can achieve the same alignment results using left or right white-spaces.

{{wiki:dokuwiki-128.png  }}
{{ wiki:dokuwiki-128.png }}
{{  wiki:dokuwiki-128.png}}

When aligned left or right, text will usually flow down beside the image on the opposite side of the page. When aligned centrally, text does not flow down either side. Section headlines always appear above and below images and never alongside.

Captioning an Image

You can also add a caption (displayed as a tooltip by most browsers), too.

This is the caption

{{ wiki:dokuwiki-128.png |This is the caption}}

Linking an Image

When inserting an image using the Media Files Window you get the option to hyperlink the embedded image to its detail page in the Media Manager, or to the original image itself, or to have no hyperlink at all, or to have no image but just a hyperlink to the original image itself. It is recommended you choose the option to link to the original image using the Link direct button or to have no link by using the No link button.

You can also link an image to another internal or external page by combining the syntax for Hyperlinks and Images like this:

[[http://www.php.net|{{wiki:dokuwiki-128.png}}]]

Please note: The image formatting is the only formatting syntax accepted in link names.

The whole Hyperlinks and Images syntax is supported (including image resizing, internal and external images and URLs and shortcut links).

In addition to Images, the Knowledge Base can be used to store other files to be made available for download by users. Download Links are often created using the Easy Ways to Contribute forms, but they can also be added to other pages.

It is possible to use the Add Images and Other Files button on the Quick Buttons toolbar to add a download link. When clicked, it opens the Media Files Window to allow you to choose the namespace and file required (or to upload a new file). When a non-image file is selected, a download link to the file will be added to the page, using the syntax:

{{ :namespace:filename.ext |caption}}

However, there is a significant disadvantage to this approach. File names within the Knowledge Base are composed entirely of lower-case characters and underscores (_), and so do files downloaded by such a link.

The recommended approach is to use the pushfile.php utility to create download links such as http://www.fhug.org.uk/pushfile.php?filename=folder/icons.zip optionally with link text like this:

[[http://www.fhug.org.uk/pushfile.php?filename=folder/icons.zip]]
[[http://www.fhug.org.uk/pushfile.php?filename=folder/icons.zip|link text]]

The utility automatically replaces each underscore in the filename with a space character as it is downloaded. Other parameters offer further options.

  • ns= specifies only a full namespace, e.g. ns=/fhugdownloads/contents, where / replaces the usual colon :.
  • name= lets the filename be changed, e.g. name=Census%20Icons, where %20 represents a space character. FIXME %20 feature not working

So to download :fhugdownloads:contents:janescensusicons.zip as Janes Census Icons would require:

[[http://www.fhug.org.uk/pushfile.php
?ns=/fhugdownloads/contents
&filename=janescensusicons.zip
&name=Janes%20Census%20Icons
|Janes Census Icons]]

Pushfile Plugin Macro

The pushfile Control Macro provides a shorthand alternative, which allows files stored in the media folder namespace of the Wiki to be “pushed” to the user, so that they are downloaded rather than displayed.

janescensusicons.zip Janes Census Icons

{{pushfile>:fhugdownloads:contents:janescensusicons.zip|Janes Census Icons}}

Either the namespace must be specified in full, or if only the filename is specified it will assume the current page namespace. Thus relative notations such as . and .: will not work.

You can use the Media Manager to identify the file namespace and name.

Media Manager and Media Files Window

The Media Manager and the Media Files Window are the tools by which images and other files are managed within the Knowledge Base. They provide facilities to:

  • Review/locate existing files
  • Use files within page content
  • Upload new files
  • Update existing files
  • Delete files

Files are grouped in namespaces (the same set of namespaces as used for pages). At the left hand side of both the Media Files and Media Manager windows, you can navigate through the namespaces to select the one you need.

The files within the selected namespace are shown on the right and can be selected to view or manipulate there.

Using the Media Files Pop-up

To open the Media Files window while editing a page (so that you can use a file within the page content) you can use the Add Images and Other Files button on the Quick Buttons toolbar; the Media Files window will open in a pop-up, in the same namespace as the page you are editing, which will normally be where you want to work with files for that page.

A thumbnail of each existing file is shown, with icons to View the Original, Open the Media Manager and Delete. At the top of the thumbnails, there are options to Select files… to Upload, and a Search field.

Selecting a file within the namespace will embed the file link in the Page being edited as described at Images and Image Links and Download Links.

Using the Media Manager

To open the Media Manager at any time, use the Tools > Media Manager command at the top right of the Knowledge Base screen; you can open it in the existing browser tab, or a new tab or new window.

Within the Media Manager, files can be viewed as thumbnails or as lists of files. Selecting a file displays a larger image (with a link above to view the original file) and details of that file on the far right of the window. There are tabs at the top of the thumbnails/list of files to Upload or Search. Underneath the larger image of a selected file there are buttons to Delete or Upload new version

Uploading a New File

Within the Media Manager, click on the Upload tab and complete the details requested. Within the Media Files window, use the Select files… and Upload. Remember to de-select the Overwrite existing files option.

By default the file will be created in the selected namespace but you can create subnamespaces by prepending them to your filename separated by colons after you select the file.

Updating an Existing File

With a file selected within the Media Manager, click on the Upload New Version button or the Upload tab and complete the details requested. Within the Media Files window, use the Select files… and Upload buttons. Remember to select the Overwrite existing files option.

Deleting a File

With a file selected, click on either the Delete button (Media Manager) or the Trashcan icon (Media Files) associated with the file.

Notes:

  • If a file is in use, you will not be allowed to delete it. The Media Manager will show the references to the file if you view the file details, so that you can determine how to proceed: either to leave the file in place or to eliminate all references to it and then delete.