我的目标是生成也可以从 github 内浏览的站点文档,因此我编写了一堆 Markdown 页面。
我正在使用maven-site-plugin
与 doxia-module-markdown
生成项目文档。
我遇到的问题是 [foo](foo.md)
形式的链接在生成的 HTML 中显示为 <a href="foo.md">foo</a>
,不是<a href="foo.html">foo</a>
.
将链接更改为指向 foo.html
会使 Github 上的内容无法浏览,在我看来 .md
→ .html
映射对于 HTML 生成的工作方式是不可或缺的,因此链接重写应该在此处进行。
下面是一个最小的重现案例,它为我生成以下输出
我是否缺少一些配置选项来获取相对链接重写,以将源文件路径也应用到目标文件路径转换?
翻译后的 HTML 包含 .md 链接。
$ 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.
最佳答案
markdown-page-generator-plugin
提供一个 transformRelativeMarkdownLinks
选项,如果选项为 true,它将把相对 URL 后缀从“.md”转换为“.html”。 (默认值: false。)
设置:
- 将
doxia-module-markdown
处理的markdown文件放在/src/site/markdown/
- 将要由
markdown-page-generator-plugin
处理的 Markdown 文件放在不同名称的文件夹中,例如/src/site/markdown_/
- 将
doxia-module-markdown
添加的html代码放入header.html
和footer.html
- 配置
markdown-page-generator-plugin
以包含header.html
和footer.html
- 配置
markdown-page-generator-plugin
将处理后的文件添加到doxia-module-markdown
使用的同一目标文件夹
调整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>
更新:
Apache Maven Doxia Markdown 模块 1.8 已更新为 "switch parser from Pegdown to Flexmark" 。因此,groupId com.ruleoftech 中使用的 markdown 生成器、artifactId markdown-page-generator-plugin 现在是 Maven Doxia 本身的一部分。
<dependency>
<groupId>org.apache.maven.doxia</groupId>
<artifactId>doxia-module-markdown</artifactId>
<version>1.8</version>
</dependency>
警告:尽管 Maven Doxia 1.8 使用 flex-markjava ,不确定所有 flexmark-java
功能是否都可以通过 Doxia 提供。如果 Doxia 没有提供所需的 flexmark-java
功能,markdown-page-generator-plugin
仍然是在 Doxia 上下文之外处理 Markdown 内容的一个选项。
关于markdown - 让 doxia-module-markdown 重写 *.md 链接,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/36708241/