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. 1 Answers
Answers 1
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
0 comments:
Post a Comment