Getting doxia-module-markdown to rewrite *.md links

Question

My goal is to generate site documentation that is also browsable from within github, so I've written a bunch of markdown pages.

I'm using maven-site-plugin with doxia-module-markdown to generate project documentation.

The problem I'm running into is that links of the form [foo](foo.md) show up in the generated HTML as <a href="foo.md">foo</a>, not <a href="foo.html">foo</a>.

Changing the link to point to foo.html would make things unbrowseable from Github, and it seems to me that the .md→.html mapping is integral to how the HTML generation works, so link rewriting should be happening here.

Below is a minimal case to repro which produces the following output for me

Am I missing some configuration option to get relative link rewriting to also apply the source file path to target file path translation?

The translated HTML contains .md links.

$ mvn clean site && cat target/site/a.html | grep -i banana
...
<p>&#x2018;A&#x2019; is for apple, <a href="b.md">&#x2018;b&#x2019;</a> is for banana.</p>

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>foo</groupId>
  <artifactId>bar</artifactId>
  <packaging>jar</packaging>
  <version>1-SNAPSHOT</version>

  <name>Foo</name>
  <description>
  Tests link rewriting using the doxia markdown module.
  </description>
  <url>https://example.com/</url>  <!-- should not affect relative URLs -->

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.5</version>
        <dependencies>
          <dependency>
            <groupId>org.apache.maven.doxia</groupId>
            <artifactId>doxia-module-markdown</artifactId>
            <version>1.7</version>
          </dependency>
        </dependencies>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <version>2.8.1</version>
      </plugin>
    </plugins>
  </build>
</project>

site.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<project>
  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-fluido-skin</artifactId>
    <version>1.5</version>
  </skin>

  <body>
    <links>
    </links>

    <menu name="docs">
      <item name="a" href="a.html"/>
      <item name="b" href="b.html"/>
    </menu>

    <menu ref="reports"/>

    <menu ref="modules"/>

    <menu ref="parent"/>
  </body>
</project>

a.md

# A

'A' is for apple, ['b'](b.md) is for banana.

b.md

# B

['A'](a.md) is for apple, 'b' is for banana.

marc-medley · Answer 1 · 2019-01-22T16:33:39.363

markdown-page-generator-plugin provides a transformRelativeMarkdownLinks option which will transform relative url suffix from ".md" to ".html" if option true. (Default: false.)

Setup:

Put markdown files to be processed by doxia-module-markdown in /src/site/markdown/
Put markdown files to be processed by markdown-page-generator-plugin in a differently named folder such as /src/site/markdown_/
Put html code added by doxia-module-markdown into header.html and footer.html
Configure markdown-page-generator-plugin to include header.html and footer.html
Configure markdown-page-generator-plugin to add processed file to the same target folder used by doxia-module-markdown

Adapt `pom.xml`:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.6</version>
  <dependencies>
    <!-- processes ${project.basedir}/src/site/markdown/ -->
    <dependency>
      <groupId>org.apache.maven.doxia</groupId>
      <artifactId>doxia-module-markdown</artifactId>
      <version>1.7</version>
    </dependency>
  </dependencies>
</plugin>
<plugin>
  <groupId>com.ruleoftech</groupId>
  <artifactId>markdown-page-generator-plugin</artifactId>
  <version>0.10</version>
  <executions>
    <execution>
      <phase>process-sources</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <inputDirectory>${project.basedir}/src/site/markdown_/</inputDirectory>
    <outputDirectory>${project.build.directory}/site/</outputDirectory>

    <!-- copy other /markdown_/* directories -->
    <copyDirectories>images_,quickstart_files</copyDirectories>

    <!-- put doxia-module-markdown additional html in these header & footer files -->
    <headerHtmlFile>${project.basedir}/src/site/markdown_/html/header.html</headerHtmlFile>
    <footerHtmlFile>${project.basedir}/src/site/markdown_/html/footer.html</footerHtmlFile>

    <!-- transform relative url suffix from ".md" to ".html" -->
    <transformRelativeMarkdownLinks>true</transformRelativeMarkdownLinks>

    <pegdownExtensions>ANCHORLINKS,HARDWRAPS,AUTOLINKS,TABLES,FENCED_CODE_BLOCKS</pegdownExtensions>
  </configuration>
</plugin>

Update:

The Apache Maven Doxia Markdown Module 1.8 was updated to "switch parser from Pegdown to Flexmark". So, markdown generator used in groupId com.ruleoftech, artifactId markdown-page-generator-plugin is now part of the Maven Doxia itself.

<dependency>
  <groupId>org.apache.maven.doxia</groupId>
  <artifactId>doxia-module-markdown</artifactId>
  <version>1.8</version>
</dependency>

Caveat: Although Maven Doxia 1.8 uses flex-markjava, it is not certain that all of the flexmark-java features are made available via Doxia. The markdown-page-generator-plugin does remain an option for working with markdown content outside the context of Doxia, if Doxia is not surfacing the desired flexmark-java features.

@l-marc-l Thank you for you answer. After the update of doxia-module-markdown to use flexmark in version 1.8, is the use of markdown-page-generator-plugin still necessary to rewrite the links from .md to .html? Thank you! — jmones, Jan 21 '19 at 14:00
@jmones Maven Doxia 1.8 uses `flexmark-java`, thus `markdown-page-generator-plugin` (a Maven `flexmark-java` plugin) _is not required with Doxia 1.8_. See [current doxia modules](https://maven.apache.org/doxia/doxia/). Although, `markdown-page-generator-plugin` does remain an option for working with markdown content outside the context of Doxia. — marc-medley, Jan 21 '19 at 19:31
@l-marc-l I suspected that, but didn't find the way to enable the rewrite link option in doxia-module-markdown. After your comment, I'll check a little bit more. Thank you! — jmones, Jan 22 '19 at 08:24
@l-marc-l I checked and still couldn't find it. It looks to me that link rewrite is achieved in `flexmark-java` implementing `com.vladsch.flexmark.html.LinkResolver`. markdown-page-generator seems to do this in [FlexmarkLinkResolver.java](https://github.com/walokra/markdown-page-generator-plugin/blob/master/src/main/java/com/ruleoftech/markdown/page/generator/plugin/FlexmarkLinkResolver.java), but I cannot find this interface implemented in [doxia-module-markdown source code](https://github.com/apache/maven-doxia/tree/doxia-1.8/doxia-modules/doxia-module-markdown). — jmones, Jan 22 '19 at 08:47
@l-marc-l I've added this issue to doxia project to request this new feature: https://issues.apache.org/jira/browse/DOXIA-584 — jmones, Jan 22 '19 at 09:09
@jmones based on your observation & jira issue, i added a caveat to the answer that Doxia's use of `flexmark-java` may not provide access to all `flexmark-java` features. thx. — marc-medley, Jan 22 '19 at 16:29

score 0 · Answer 2 · edited May 23 '17 at 11:45

0

If you are hosting your files on a server and you have access to your website directory, you could try using the .htaccess file that should be at the root of the directory where your MD files are in.

In .htaccess, add this:

RewriteEngine On
RewriteRule /(.*).md /$1.html

If you know a bit of Regex, you will notice that the RewriteRule is capturing the name of your .md file and converting it to a .html. This works with all requests of .md files, and does not edit anything in GitHub or the distant server. For more details, check this post on how to rewrite URLs using .htaccess

edited May 23 '17 at 11:45

Community

1
1

answered Apr 29 '16 at 08:21

TheSola10

697
6
16

Thanks, but I'd really like to get the markdown translator to do it, because it better understands the difference between `.md` in github /blob links and those in relative links. I've already got something hacky like this in perl but it's less than ideal. – Mike Samuel Apr 30 '16 at 18:54
@MikeSamuel Uh-huh. However `.htaccess` will leave every files untouched, thus not affecting external links (i.e those pointing to github from the site) – TheSola10 May 01 '16 at 14:41