CODEWITHSUNDEEP
markdownmaven-site-plugindoxia
Mike Samuel
Mike Samuel

Reputation: 120516

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

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.

Upvotes: 3

Views: 1474

Answers (2)

marc-medley
marc-medley

Reputation: 9832

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.

Upvotes: 3

TheSola10
TheSola10

Reputation: 697

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

Upvotes: 0

Related Questions