获取doxia-module-markdown以重写* .md链接
[英]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. 
我的目标是生成可以从github中浏览的站点文档，所以我写了一堆降价页面。
I'm using maven-site-plugin with doxia-module-markdown to generate project documentation. 我正在使用带有doxia-module-markdown maven-site-plugin来生成项目文档。
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> . 我[foo](foo.md)的问题是[foo](foo.md)形式的链接在生成的HTML中显示为<a href="foo.md">foo</a> ，而不是<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. 将链接更改为指向foo.html会使Github无法显示，并且在我看来.md → .html映射是HTML生成工作方式的组成部分，因此链接重写应该在这里发生。
Below is a minimal case to repro which produces the following output for me 下面是repro的最小案例，它为我生成以下输出
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. 翻译的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 的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 的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.md
# A
'A' is for apple, ['b'](b.md) is for banana.
b.md b.md
# B
['A'](a.md) is for apple, 'b' is for banana.
2 个解决方案
解决方案1
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. markdown-page-generator-plugin提供了transformRelativeMarkdownLinks选项，如果选项为true，它将相对url后缀从“.md”转换为“.html”。 (Default: false.) （默认值：false。）
Setup: 建立：
- Put markdown files to be processed by
doxia-module-markdownin/src/site/markdown/将doxia-module-markdown文件放在/src/site/markdown/doxia-module-markdown中 - Put markdown files to be processed by
markdown-page-generator-pluginin a differently named folder such as/src/site/markdown_/将markdown文件放入markdown markdown-page-generator-plugin不同名称的文件夹，例如/src/site/markdown_/ - Put html code added by
doxia-module-markdownintoheader.htmlandfooter.html将doxia-module-markdown添加的html代码放入header.html和footer.html - Configure
markdown-page-generator-pluginto includeheader.htmlandfooter.html配置markdown-page-generator-plugin以包含header.html和footer.html - Configure
markdown-page-generator-pluginto add processed file to the same target folder used bydoxia-module-markdown配置markdown-page-generator-plugin将处理后的文件添加到doxia-module-markdown使用的同一目标文件夹中
Adapt pom.xml : 适应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" . Apache Maven Doxia Markdown模块1.8更新为“将解析器从Pegdown切换到Flexmark” 。 So, markdown generator used in groupId com.ruleoftech, artifactId markdown-page-generator-plugin is now part of the Maven Doxia itself. 因此，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>
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. 警告：尽管Maven Doxia 1.8使用flex-markjava ，但不确定所有的flexmark-java功能是否都可以通过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. 如果Doxia没有出现所需的flexmark-java功能，那么markdown-page-generator-plugin仍然是在Doxia上下文之外处理markdown内容的选项。
解决方案2
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. 如果您在服务器上托管文件并且可以访问网站目录，则可以尝试使用.htaccess文件，该文件应位于MD文件所在目录的根目录中。
In .htaccess , add this: 在.htaccess ，添加以下内容：
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 . 如果你知道一点Regex，你会注意到RewriteRule正在捕获.md文件的名称并将其转换为.html 。 This works with all requests of .md files, and does not edit anything in GitHub or the distant server. 这适用于.md文件的所有请求，并且不会在GitHub或远程服务器中编辑任何内容。 For more details, check this post on how to rewrite URLs using .htaccess 有关更多详细信息，请查看此文章 ，了解如何使用.htaccess重写URL
声明:本站的技术帖子网页，遵循CC BY-SA 4.0协议，如果您需要转载，请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.