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>‘A’ is for apple, <a href="b.md">‘b’</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.
2 answers
solution1
3 2017-01-22 06:53:06
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-markdownin/src/site/markdown/ - Put markdown files to be processed by
markdown-page-generator-pluginin a differently named folder such as/src/site/markdown_/ - Put html code added by
doxia-module-markdownintoheader.htmlandfooter.html - Configure
markdown-page-generator-pluginto includeheader.htmlandfooter.html - Configure
markdown-page-generator-pluginto add processed file to the same target folder used bydoxia-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.
solution2
0 2016-04-29 08:21:54
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
The technical post webpages of this site follow the CC BY-SA 4.0 protocol. If you need to reprint, please indicate the site URL or the original address.Any question please contact:yoyou2525@163.com.