python - page - MkDocs y MathJax

mkdocs build path

Question

Soy nuevo en MkDocs y estoy escribiendo una documentación técnica que requiere látex. He construido con éxito un pequeño sitio web con uno de los temas de MkDocs, sin embargo, no mostrará correctamente las ecuaciones de látex. Seguí las instrucciones en

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

así como las instrucciones que siguen al enlace python-markdown-mathjax desde esa página. También he intentado agregar líneas apropiadas a mi archivo mkdocs.yaml, similar a:

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

Sin embargo, al emitir el comando ''mkdocs build'' todavía se obtiene un sitio que no representa las ecuaciones. También he intentado agregar un indicador -x mathjax con el comando mkdocs build.

He rastreado la web y he estado jugando durante un buen rato ahora. ¿Puede alguien aclarar qué debo hacer para que estos dos jueguen juntos?

Answer 1

Aquí hay una forma de obtener LaTeX en MkDocs con la extensión arithmatex .

Estoy respondiendo nuevamente porque quiero documentar una solución que no se vincule con sitios de terceros como Cloudflare y Google.

Sigo el camino con el tema llamado mkdocs-material pero puedes reemplazar el theme: ...school por theme: readthedocs .

Primero instale MkDocs y cree un proyecto: https://www.mkdocs.org/#installation .

Luego instale mkdocs-material y MathJax siguiente manera. Digamos que el proyecto se llama my-project . Utilice descargas y no pip porque quiere cambiar el CDN a Cloudflare y el enlace a google.

cd my-project
git clone https://github.com/squidfunk/mkdocs-material.git
git clone https://github.com/mathjax/MathJax.git MathJax

Edite mkdocs.yml como se describe en "Uso" , por ejemplo:

site_name: My Project
pages:
    - Home: index.md
theme:
    name: null
    custom_dir: ''mkdocs-material/material''
    palette:
        primary: amber
        accent: pink
    language: de
    feature:
        tabs: true
    font: false
    logo:
        icon: school
markdown_extensions:
    - pymdownx.arithmatex
extra_javascript:
    - ../MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML

Puede insertar algunos TeX en index.md , compilar el sitio ( mkdocs build ) y abrir el index.html para verificar que MathJax funciona. Debido a que no funciona con el mkdocs serve , cargué la carpeta MathJax y la mkdocs serve a ella en lugar del enlace a la ruta local.

extra_javascript:
    - https://mysite/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML

Para activar TeX en línea con $...$ , debe crear un archivo JS adicional

cd docs
mkdir assets
touch extra.js

Inserte el siguiente texto en extra.js :

window.MathJax = {
  tex2jax: {
    inlineMath: [ ["$","$"], ["//(","//)"] ],
    displayMath: [ ["//[","//]"] ]
  },
  TeX: {
    TagSide: "right",
    TagIndent: ".8em",
    MultLineWidth: "85%",
    equationNumbers: {
      autoNumber: "AMS",
    },
    unicode: {
      fonts: "STIXGeneral,''Arial Unicode MS''"
    }
  },
  displayAlign: "center",
  showProcessingMessages: false,
  messageStyle: "none"
};

y enlace a él en mkdocs.yml . Finalmente, la sección extra_javascript puede ser así:

extra_javascript:
    - https://mysite/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML
    - assets/extra.js

Como no queremos usar CDN, puede editar mkdocs-material/material/base.html y eliminar / descomentar la línea con <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin> . La fuente impresionante y los iconos de material ya están a bordo dentro de mkdocs-material.

Answer 2

Deberá instalar la extensión como se indica en el archivo README de github. Suena como si ya lo hayas hecho.

Luego debe decirle a Mkdocs que está usando esta extensión de Python Markdown. Haría esto teniendo una línea como esta en su mkdocs.yaml: markdown_extensions: [mathjax]

La documentación de configuración de YAML se puede encontrar en:

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

Answer 3

Esto es realmente más fácil de lo que esperaba. Primero instalé la github.com/mitya57/python-markdown-math :

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

Luego creé un nuevo proyecto MkDocs:

mkdocs new test_math

Luego test_math/docs/index.md archivo test_math/docs/index.md para que sea como sigue (ejemplo tomado de la documentación de 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}.$$

Finalmente, test_math/config.yaml archivo test_math/config.yaml como sigue:

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

No estaba seguro de si esto funcionaría, pero ejecuté el servidor de prueba para ver:

mkdocs serve

Entonces abrí mi navegador y cargué http://127.0.0.1:8000/ . La página mostrada con las ecuaciones de muestra correctamente formateadas:

Luego recordé que el OP solicitó que esto funcionara con ReadTheDocs, así que agregué la siguiente línea a la configuración:

theme: readthedocs

Mi navegador se recargó y se muestran las siguientes (ecuaciones correctamente formateadas):

Debo tener en cuenta que recibo un error extraño al no cargar fontawesome. Con el tema de MkdDocs, las ecuaciones desaparecen después de un minuto (cuando aparece el error en la consola del navegador). Sin embargo, en el tema de ReadTheDocs, las ecuaciones se muestran correctamente, incluso con el error. De cualquier manera, creo que este error está relacionado con algún otro problema en mi máquina local.

Finalmente, el Bounty es ...

Buscando una respuesta a partir de fuentes creíbles y / o oficiales.

Normalmente no hago publicidad de esto, pero como me preguntaste, soy el desarrollador líder de Python-Markdown, trabajo regularmente con mitya57 (el creador de Python-Markdown-Math Extension) ya que es uno de los otros dos desarrolladores con acceso comprometido. a Python-Markdown, y soy un colaborador de MkDocs (una de esas contribuciones es el soporte para las extensiones de Python-Markdown).

Answer 4

Parece que esta extensión no es necesaria:

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

Parece funcionar.