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 ishtml
. 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 alsoEdit this page
. This option takes effect only whenlink_type
is set tohtml
. link_html_attributes
- Additional HTML attributes for the hyperlink. By using CSS in combination with
class
attribute, and/orstyle
attribute, you may customize the presentation of your hyperlinks. Default value is an empty string. This option takes effect only whenlink_type
is set tohtml
. 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.