Skip to content

RepoLink

This preprocessor allows to add into each Markdown source a hyperlink to the related file in Git repository. Applying of the preprocessor to subprojects allows to get links to separate repositories from different pages of a single site (e.g. generated with MkDocs).

By default, the preprocessor emulates MkDocs behavior. The preprocessor generates HTML hyperlink with specific attributes and inserts the link after the first heading of the document. The default behavior may be overridden.

The preprocessor supports the same options repo_url and edit_uri as MkDocs.

Installation

RepoLink preprocessor is a part of MultiProject extension:

Usage

To enable the preprocessor, add repolink to preprocessors section in the project config:

preprocessors:
    - repolink

The preprocessor has a number of options:

preprocessors:
    - repolink:
        repo_url: https://github.com/foliant-docs/docs/
        edit_uri: /blob/master/src/
        link_type: html
        link_location: after_first_heading
        link_text: ""
        link_title: View the source file
        link_html_attributes: "class=\"md-icon md-content__icon\" style=\"margin: -7.5rem 0\""
        targets:
            - pre
repo_url
URL of the related repository. Default value is an empty string; in this case the preprocessor does not apply. Trailing slashes do not affect.
edit_uri
Revision-dependent part of URL of each file in the repository. Default value is /blob/master/src/. Leading and trailing slashes do not affect.
link_type
Link type: HTML (html) or Markdown (markdown). Default value is html.
link_location
Place in the document to put the hyperlink. By default, the hyperlink is placed after the first heading, and newlines are added before and after it (after_first_heading). Other values: before_content—the hyperlink is placed before the content of the document, the newline after it is provided; after_content—the hyperlink is placed after the content of the document, the newline before it is added; defined_by_tag—the tags <repo_link></repo_link> that are met in the content of the document are replaced with the hyperlink.
link_text
Hyperlink text. Default value is Edit this page.
link_title
Hyperlink title (the value of title HTML attribute). Default value is also Edit this page. This option takes effect only when link_type is set to html.
link_html_attributes
Additional HTML attributes for the hyperlink. By using CSS in combination with class attribute, and/or style attribute, you may customize the presentation of your hyperlinks. Default value is an empty string. This option takes effect only when link_type is set to html.
targets
Allowed targets for the preprocessor. If not specified (by default), the preprocessor applies to all targets.

You may override the value of the edit_uri config option with the FOLIANT_REPOLINK_EDIT_URI system environment variable. It can be useful in some non-stable testing or staging environments.

Back to top