让 doxia-module-markdown 重写 *.md 链接答案

【问题标题】：Getting doxia-module-markdown to rewrite *.md links让 doxia-module-markdown 重写 *.md 链接
【发布时间】：2016-04-19 03:51:45
【问题描述】：

我的目标是生成也可以从 github 中浏览的站点文档，因此我编写了一堆降价页面。

我正在使用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>&#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.

【问题讨论】：

标签： markdown maven-site-plugin doxia

【解决方案1】：

markdown-page-generator-plugin 提供了一个transformRelativeMarkdownLinks 选项，如果选项为真，该选项会将相对 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 上下文之外处理降价内容的一个选项。

【讨论】：

@l-marc-l 谢谢你的回答。 doxia-module-markdown在1.8版本更新为使用flexmark后，是否还需要使用markdown-page-generator-plugin将链接从.md重写为.html？谢谢！
@jmones Maven Doxia 1.8 使用 flexmark-java，因此 markdown-page-generator-plugin（一个 Maven flexmark-java 插件）Doxia 1.8 不需要。见current doxia modules。虽然，markdown-page-generator-plugin 仍然是在 Doxia 上下文之外处理降价内容的一个选项。
@l-marc-l 我怀疑是这样，但没有找到在 doxia-module-markdown 中启用重写链接选项的方法。在你的评论之后，我会检查更多。谢谢！
@l-marc-l 我查了下还是没找到。在我看来，链接重写是在实现com.vladsch.flexmark.html.LinkResolver 的flexmark-java 中实现的。 markdown-page-generator 似乎在FlexmarkLinkResolver.java 中执行此操作，但我在doxia-module-markdown source code 中找不到此接口。
@l-marc-l 我已将此问题添加到 doxia 项目以请求此新功能：issues.apache.org/jira/browse/DOXIA-584

【解决方案2】：

如果您将文件托管在服务器上并且您可以访问您的网站目录，则可以尝试使用应该位于 MD 文件所在目录根目录的 .htaccess 文件。

在.htaccess 中添加：

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

如果您了解一点正则表达式，您会注意到RewriteRule 正在捕获您的.md 文件的名称并将其转换为.html。这适用于.md 文件的所有请求，并且不会编辑 GitHub 或远程服务器中的任何内容。有关更多详细信息，请查看 this post 了解如何使用 .htaccess 重写 URL