MkDocs и MathJax

Я новичок в MkDocs и пишу техническую документацию, требующую латекс. Я успешно создал небольшой веб-сайт с одной из тем MkDocs, однако он не будет правильно отображать уравнения латекса. Я выполнил следующие инструкции:

http://www.vlfeat.org/matconvnet/developers/

а также инструкции, следующие за ссылкой на python-markdown-mathjax с этой страницы. Я также занялся добавлением соответствующих строк в файл mkdocs.yaml, похожий на:

https://github.com/EdyJ/vehicle-physics-docs/blob/master/mkdocs.yml

Однако выдача команды "mkdocs build" по-прежнему приводит к сайту, который не отображает уравнения. Я также попытался добавить флаг -x mathjax с командой сборки mkdocs.

Я прочесываю паутину и уже много времени занимаюсь ремеслом. Может ли кто-нибудь пролить свет на то, что мне нужно сделать, чтобы эти двое играли вместе?

Ответ 1

Это на самом деле легче, чем я ожидал. Сначала я установил расширение Python-Markdown-Math:

pip install https://github.com/mitya57/python-markdown-math/archive/master.zip

Затем я создал новый проект MkDocs:

mkdocs new test_math

Далее я редактировал файл test_math/docs/index.md следующим образом (образец заимствован из Документация MathJax):

# MathJax Test Page

When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

Наконец, я редактировал файл test_math/config.yaml следующим образом:

site_name: Test Math

extra_javascript: 
    - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML

markdown_extensions:
    - mdx_math

Я не знал, будет ли это работать, но я запустил тестовый сервер, чтобы увидеть:

mkdocs serve

Затем я открыл мой браузер и загрузил http://127.0.0.1:8000/. Страница, отображаемая с правильными отформатированными уравнениями:

Затем я вспомнил, что OP попросил, чтобы это работало с ReadTheDocs, поэтому я добавил следующую конфигурацию в конфигурацию:

theme: readthedocs

Мой браузер перезагружен и отображаются следующие (правильно отформатированные уравнения):

Я должен отметить, что я получаю какую-то странную ошибку о fontawesome, не загружая. С темой MkdDocs уравнения исчезают через минуту (когда ошибка появляется в консоли браузера). Однако в теме ReadTheDocs уравнения отображаются правильно, даже с ошибкой. В любом случае, я считаю, что эта ошибка связана с некоторыми другими проблемами на моей локальной машине.

Наконец, Bounty - это...

Ищите ответный рисунок из достоверных и/или официальных источников

Я обычно не рекламирую это, но, поскольку вы спросили, я ведущий разработчик Python-Markdown, я регулярно работаю с mitya57 (создателем Python-Markdown-Math Extension), поскольку он является одним из двух другие разработчики с фиксацией доступа к Python-Markdown, и я являюсь автором MkDocs (одним из этих вкладов является поддержка расширений Python-Markdown).

Ответ 2

Вам нужно будет установить расширение, как указано в github README. Звучит так, будто вы уже это сделали.

Затем вам нужно сообщить Mkdocs, что вы используете расширение Python Markdown. Вы сделали бы это, имея такую строку в своем mkdocs.yaml: markdown_extensions: [mathjax]

Документацию по конфигурации YAML можно найти по адресу:

http://www.mkdocs.org/user-guide/configuration/#formatting-options

Ответ 3

Похоже, что это расширение не требуется:

Docs/mathjaxhelper.js

MathJax.Hub.Config({
  "tex2jax": { inlineMath: [ [ '$', '$' ] ] }
});
MathJax.Hub.Config({
  config: ["MMLorHTML.js"],
  jax: ["input/TeX", "output/HTML-CSS", "output/NativeMML"],
  extensions: ["MathMenu.js", "MathZoom.js"]
});

mkdocs.yml

markdown_extensions:
  - extra
  - tables
  - fenced_code
extra_javascript:
  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML
  - mathjaxhelper.js

Кажется, это трюк.