Получение doxia-module-markdown для перезаписи ссылок *.md

Моя цель - создать документацию сайта, которая также доступна для просмотра из 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.
Источник

2 ответа

markdown-page-generator-plugin обеспечивает transformRelativeMarkdownLinks опция, которая преобразует относительный суффикс url из ".md" в ".html", если опция true. (По умолчанию: false.)

Настроить:

  • Поместите файлы уценки, которые будут обработаны doxia-module-markdown в /src/site/markdown/
  • Поместите файлы уценки, которые будут обработаны markdown-page-generator-plugin в папке с другим именем, такой как /src/site/markdown_/
  • Положите HTML-код, добавленный doxia-module-markdown в 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 был обновлен для "переключения парсера с Pegdown на Flexmark". Итак, генератор уценок, используемый в groupId com.ruleoftech, artifactId markdown-page-generator-plugin теперь является частью самой Maven Doxia.

<dependency>
  <groupId>org.apache.maven.doxia</groupId>
  <artifactId>doxia-module-markdown</artifactId>
  <version>1.8</version>
</dependency>
Источник

Если вы размещаете свои файлы на сервере и у вас есть доступ к каталогу вашего веб-сайта, вы можете попробовать использовать .htaccess файл, который должен находиться в корне каталога, в котором находятся ваши MD-файлы.

В .htaccess, Добавь это:

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

Если вы немного знакомы с Regex, вы заметите, что RewriteRule захватывает имя вашего .md файл и преобразовать его в .html, Это работает со всеми запросами .md файлы, и ничего не редактирует в GitHub или удаленном сервере. Для получения более подробной информации, проверьте этот пост о том, как переписать URL с помощью .htaccess

Источник
Другие вопросы по тегам