问题标签 [mkdocs]

我不是一个真正的 html/css/js 人，但我正在为MkDocs中的一个项目做文档，其中包含Material theme。这里的问题是我有非常宽的表格，它们在 Chrome 和 Firefox 中的显示方式不同，更具体地说——它们在 Firefox 中是完全不可接受的。

默认情况下，Chrome 可以很好地显示表格，它会选择看起来非常漂亮且合理的列宽：

https://monosnap.com/file/LvtSxXhE5muFpz8aKhTPvbuoNkMOMN

不幸的是，在 Firefox 中，表格溢出了我认为不应该发生的容器：

https://monosnap.com/file/u9bAq7pGarmGE5hhgawF84ah451HZz

我尝试了不同的解决方案来解决这个问题，但最终无法找到让它在 Firefox 中看起来像在 Chrome 中一样的方法。似乎 Chrome 使用了一些逻辑来以漂亮的方式显示表格。

我最接近 Chrome 版本的是使用以下 css：

它将强制表格留在容器内并且不会溢出，但是表格如何为列选择宽度并不好：

https://monosnap.com/file/SJ6T20vIHpRTW5sy3RAa8RfY1Uchiq

我在 Github 页面上创建了一个演示：https ://sspkmnd.github.io/mkdocs-table-layout-problem （repo – https://github.com/sspkmnd/mkdocs-table-layout-problem）希望这会帮助查看差异。此外，还有一个按钮table-layout: fixed;可以更改表格的样式，因此您可以看到和之间的区别table-layout: auto;——它就在表格的上方。

问题是：

1. 有没有办法让它在 Firefox 中看起来像在 Chrome 中一样？
2. 为什么默认情况下它会溢出 Firefox 中的容器？我想这不应该发生。

PS：我想有一种方法可以以百分比为列显式设置宽度。我试图做到这一点，但我没有找到一种方法 <th>通过 Markdown （这是源代码）将一个类分配给一个表。

任何想法将不胜感激！

背景

我们正在将用 LaTeX 和 MS Word 编写的文档合并到降价（为了众所周知的优势）。我们有一个创建mkdocs的静态 Intranet 站点。我的前辈决定使用MathJax，但是在MathJax CDN 关闭的那一刻就停止了工作，但是客户只是延迟了一段时间才意识到这一点。与此同时，我们的客户（他们的公式应该保留在栅栏后面）现在完全断开了内部网与外部世界的连接。因此，不再可以选择使用不同的 MathJax CDN。

挑战

我们必须使用哪些选项来呈现公式？使用完整的 LaTeX 安装（类似于http://quicklatex.com/）即时渲染 LaTeX 公式并不太复杂 - 除了我们没有获得这样做的许可。

我们可以坚持使用 MathJax 吗？我们如何认为在不连接 CDN 的情况下运行 MathJax 很简单？有没有其他的解决方案来渲染简单的数学公式mkdocs？

评论

我故意使用标签latex和MathJax（尽管它不是严格与 Latex 和 MathJax 相关的），因为我很欣赏你关于如何快速、简单和安全地呈现公式的创意。

相关问题

• MkDocs 和 MathJax
• 带有 mkdocs 的本地 mathjax
• 更新 MathJax CDN
• 如何从本地 Happstack 服务器提供 MathJax？

有一个 GitHub 存储库，我喜欢对其 docs 进行更改。它使用 readthedocs 来托管主题，并使用 mkdocs。

我正在使用 macOS Mojave。

我找到了这个https://docs.readthedocs.io/en/latest/install.html安装指南来安装readthedocs。但是我看不到在更改要更改的存储库的文件后如何测试构建的文件mkdocs.yml。

mkdocs.yml那么，当我在 macOS X中对本地进行更改时，如何为 readthedocs 测试构建的文件呢？

如果有必要，我不介意使用 docker。

我正在使用的 mkdocs.yml 导航文件包括一个手册网站的层次结构树，其中包含内容文章所属的多个类别和子类别；树是绝对虚拟的，而不是基于文件夹结构/网站路径。我正在寻找一种为每个树的节点（类别）生成永久链接的方法。如果 Markdown 或其扩展无法做到这一点，那么也许可以使用 html/css 元素。

我对 Markdown 和 mkdocs 很陌生；我彻底搜索了一个解决方案，但没有找到一个。

构建的具有可扩展节点的虚拟分层树是可以的，但我确实需要为每个类别和子类别生成永久链接，例如 example.net/docs/guides/toplevelcat/bottomlevelcat 或 example.net/docs/guides/toplevelcat# bottomlevelcat 链接的组织方式以及它们是自动生成还是手动预设都无关紧要

该链接可能会指向一个索引页面，其中包含属于该类别的所有手册，或者仅显示根mysite.net/docs/guides/页面并展开所需的类别

我有一个使用 Jinja2 的 MkDocs 站点模板。我正在尝试添加指向每个页面的 PDF 版本的链接。PDF 始终与 markdown 文件同名。所以我试图在模板中添加一个链接，该链接将自动针对每个页面的正确 PDF。这比让作者在每个页面上添加手动链接感觉更干净。

<a href="{{ page.url|url }}.pdf">Download</a>

以上几乎是正确的，但所有 URL 的末尾都有一个“/”。意思是结果是：

page/url/slug/.pdf

MkDocs 和 Jinja 似乎都没有提供过滤器来删除斜杠，所以我想知道是否可以使用正则表达式来删除它。我相信这会很简单\/$？但是，我从文档中看不到如何在 Jinja 中应用正则表达式过滤器？

我正在使用带有 codehilite markdown 扩展的 MkDocs

我只想为特定的代码片段启用代码片段行号。

如果我设置

在我的 mkdocs.yml 中，这将为所有代码片段启用行号。

我看到可以通过使用 shebang 语言说明符和双缩进来激活特定片段的行号：

但是，我更喜欢使用反引号 (```) 来指定代码。

有没有办法在使用反引号时为特定代码列表启用行号？

I am setting up a documentation using mkdocs but I am getting "NotImplementedError" when runing the "mkdocs serve" command

Note that I am working on windows 10 and installed the Python 3.8.0a3 version

I would like to get where the error come from and fix it

我正在尝试将mkdocs与mknotebooks一起使用，以使用 Jupyter Notebook 和 markdown 文件构建网站。一切都很好，除了生成的 html 页面中输入和输出单元格的视觉外观是相同的，因此很难理解。

例如，在笔记本中，输入和输出单元格不同，如下所示：

但是，当我导出到 markdown，然后导出到 html 时，它们看起来相似：

我尝试用 CSS 处理这个问题。但是，div输入和输出单元的 s 不是不同的类，因此很难定义不同的样式。

我目前正在玩nbconvert markdown templates。但是，我不知道要修改什么，以使输出单元格看起来不同。默认情况下，它们缩进 1 个制表符空格，这在导出为 HTML 时似乎不足以区分它们。

我的自定义模板文件如下所示：

我目前要离开实习岗位，并且正在为毕业后接任的暑期实习生编写文档。我已经使用 MkDocs 在 Markdown 中编写了我的所有文档，并且准备部署它们。我的文档使用 MkDocs 附带的 Read the Docs 主题，我希望将它们托管在 RTD 上。但是，我的文档代码托管在属于我公司 GitHub 组织的私有存储库中。我在使用 RTD 设置它们时遇到了问题，因为我个人并不拥有该存储库。你们中有人有这方面的经验吗？我查看了 MkDocs 'Deploying your docs'，但所有超链接都已过时，该指南主要涵盖链接公共存储库。

另外——我没有嫁给 RTD，这只是我在我的文档中使用的 MkDocs 主题，所以如果你们中的任何人有其他建议，开火吧！

我想将用 RST（重组文本）编写的 Robot Framework 的用户指南转换为 Markdown，以便能够将这种伟大的工作安宁作为mkdocs站点进行托管。我已经尝试使用pandoc转换指南的 html 版本（请参见此处），但结果不是我喜欢的那样。

现在我想尝试转换用于生成用户指南的 html 版本的原始 RST 文件。用户指南的来源包括几个 RST 和其他文件

• 角色.rst
• 用户指南.css
• RobotFrameworkUserGuide.rst
• 子文件夹中的一堆 .rst 文件

是否可以使用 pandoc 或其他工具一次转换整个结构？

您建议采取哪些步骤将 RST 源转换为 Markdown，以尽可能降低转换后手动编辑的需求（请记住，源更新也必须适应 Markdown 版本)?