我希望在共享由 RTD 托管和构建的 mkdocs 文档的链接时有图像预览。我需要覆盖网站的 HTML 标头并添加开放图形协议。
经过一番调查，我发现了一些关于 Material 主题的 HTML 覆盖的资源：
https://squidfunk.github.io/mkdocs-material/reference/meta-tags/
https://rohancragg.co.uk/writing/social-media-sharing/
像这样的 sphinx 插件将是理想的选择：
https://github.com/wpilibsuite/sphinxext-opengraph
不幸的是，我在我的文档中使用 mkdocs 和 readthedocs 主题，显然，这并不完全支持元扩展：
这就是我所做的：
我能够添加扩展并链接包含开放图形协议的 main.html 覆盖。链接共享效果很好！不幸的是，现在我文档中的所有页面都以白色呈现。我在构建的日志中没有收到错误消息（如下），或者我忽略了某些内容。
查看原始 html，我可以看到标头现在仅包含 opengraph 协议，正文为空：
<html data-lt-installed="true">
<head>
<meta property="og:type" content="website">
<meta property="og:title" content="Faceit Documentation - Overview">
<meta property="og:description" content="Faceit - Auto-Rig IPhoneX Shape Keys (Blendshapes) - Performance Capture for ANY Character!">
<meta property="og:url" content="https://faceit-doc.readthedocs.io/">
<meta property="og:image" content="https://ia.media-imdb.com/images/rock.jpg">
</head>
<body>
</body>
</html>
本质上，我想知道是否有一种方法可以将元标记添加到 readthedocs 主题中的标题中，类似于 Material 主题中可能的内容。
这是来自 readthedocs 的构建日志：
Read the Docs build information
Build id: 14195757
Project: faceit-doc
Version: v2
Commit: 600a315069246da2bb770304f88cadb6ca3d6426
Date: 2021-07-08T14:56:54.817314Z
State: finished
Success: True
[rtd-command-info] start-time: 2021-07-08T14:56:55.980380Z, end-time: 2021-07-08T14:56:59.243670Z, duration: 3, exit-code: 0
git clone --no-single-branch --depth 50 https://gitlab.com/f-brar/faceit_doc.git .
Cloning into '.'...
[rtd-command-info] start-time: 2021-07-08T14:56:59.398910Z, end-time: 2021-07-08T14:56:59.981942Z, duration: 0, exit-code: 0
git checkout --force origin/v2
Note: checking out 'origin/v2'.
You are in a 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you to create, you may do so (now or later) by using -b with the checkout command again. Example:
git checkout -b <new-branch-name>
HEAD is now at 600a315 restore overrides
[rtd-command-info] start-time: 2021-07-08T14:57:00.159294Z, end-time: 2021-07-08T14:57:00.223086Z, duration: 0, exit-code: 0
git clean -d -f -f
[rtd-command-info] start-time: 2021-07-08T14:57:00.340941Z, end-time: 2021-07-08T14:57:00.405472Z, duration: 0, exit-code: 0
git rev-parse HEAD
600a315069246da2bb770304f88cadb6ca3d6426
[rtd-command-info] start-time: 2021-07-08T14:57:01.720061Z, end-time: 2021-07-08T14:57:05.558422Z, duration: 3, exit-code: 0
python3.7 -mvirtualenv /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2
Using base prefix '/home/docs/.pyenv/versions/3.7.9'
New python executable in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/bin/python3.7
Also creating executable in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/bin/python
Installing setuptools, pip, wheel...
done.
[rtd-command-info] start-time: 2021-07-08T14:57:05.703925Z, end-time: 2021-07-08T14:57:06.743957Z, duration: 1, exit-code: 0
/home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/bin/python -m pip install --upgrade --no-cache-dir pip setuptools
Requirement already satisfied: pip in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (21.1.3)
Requirement already satisfied: setuptools in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (57.1.0)
[rtd-command-info] start-time: 2021-07-08T14:57:06.877227Z, end-time: 2021-07-08T14:57:16.815885Z, duration: 9, exit-code: 0
/home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/bin/python -m pip install --upgrade --no-cache-dir mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 mkdocs
Collecting mock==1.0.1
Downloading mock-1.0.1.zip (861 kB)
Collecting pillow==5.4.1
Downloading Pillow-5.4.1-cp37-cp37m-manylinux1_x86_64.whl (2.0 MB)
Collecting alabaster!=0.7.5,<0.8,>=0.7
Downloading alabaster-0.7.12-py2.py3-none-any.whl (14 kB)
Collecting commonmark==0.8.1
Downloading commonmark-0.8.1-py2.py3-none-any.whl (47 kB)
Collecting recommonmark==0.5.0
Downloading recommonmark-0.5.0-py2.py3-none-any.whl (9.8 kB)
Collecting mkdocs
Downloading mkdocs-1.2.1-py3-none-any.whl (6.3 MB)
Collecting future
Downloading future-0.18.2.tar.gz (829 kB)
Collecting sphinx>=1.3.1
Downloading Sphinx-4.0.3-py3-none-any.whl (2.9 MB)
Collecting docutils>=0.11
Downloading docutils-0.17.1-py2.py3-none-any.whl (575 kB)
Collecting sphinxcontrib-applehelp
Downloading sphinxcontrib_applehelp-1.0.2-py2.py3-none-any.whl (121 kB)
Collecting Pygments>=2.0
Downloading Pygments-2.9.0-py3-none-any.whl (1.0 MB)
Collecting snowballstemmer>=1.1
Downloading snowballstemmer-2.1.0-py2.py3-none-any.whl (93 kB)
Collecting imagesize
Downloading imagesize-1.2.0-py2.py3-none-any.whl (4.8 kB)
Collecting requests>=2.5.0
Downloading requests-2.25.1-py2.py3-none-any.whl (61 kB)
Collecting Jinja2>=2.3
Downloading Jinja2-3.0.1-py3-none-any.whl (133 kB)
Collecting sphinxcontrib-devhelp
Downloading sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl (84 kB)
Collecting sphinxcontrib-htmlhelp
Downloading sphinxcontrib_htmlhelp-2.0.0-py2.py3-none-any.whl (100 kB)
Collecting sphinxcontrib-qthelp
Downloading sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl (90 kB)
Collecting packaging
Downloading packaging-21.0-py3-none-any.whl (40 kB)
Collecting sphinxcontrib-jsmath
Downloading sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl (5.1 kB)
Requirement already satisfied: setuptools in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from sphinx>=1.3.1->recommonmark==0.5.0) (57.1.0)
Collecting sphinxcontrib-serializinghtml
Downloading sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl (94 kB)
Collecting babel>=1.3
Downloading Babel-2.9.1-py2.py3-none-any.whl (8.8 MB)
Collecting pytz>=2015.7
Downloading pytz-2021.1-py2.py3-none-any.whl (510 kB)
Collecting MarkupSafe>=2.0
Downloading MarkupSafe-2.0.1-cp37-cp37m-manylinux2010_x86_64.whl (31 kB)
Collecting certifi>=2017.4.17
Downloading certifi-2021.5.30-py2.py3-none-any.whl (145 kB)
Collecting urllib3<1.27,>=1.21.1
Downloading urllib3-1.26.6-py2.py3-none-any.whl (138 kB)
Collecting idna<3,>=2.5
Downloading idna-2.10-py2.py3-none-any.whl (58 kB)
Collecting chardet<5,>=3.0.2
Downloading chardet-4.0.0-py2.py3-none-any.whl (178 kB)
Collecting mergedeep>=1.3.4
Downloading mergedeep-1.3.4-py3-none-any.whl (6.4 kB)
Collecting importlib-metadata>=3.10
Downloading importlib_metadata-4.6.1-py3-none-any.whl (17 kB)
Collecting Markdown>=3.2.1
Downloading Markdown-3.3.4-py3-none-any.whl (97 kB)
Collecting PyYAML>=3.10
Downloading PyYAML-5.4.1-cp37-cp37m-manylinux1_x86_64.whl (636 kB)
Collecting click>=3.3
Downloading click-8.0.1-py3-none-any.whl (97 kB)
Collecting ghp-import>=1.0
Downloading ghp-import-2.0.1.tar.gz (11 kB)
Collecting pyyaml-env-tag>=0.1
Downloading pyyaml_env_tag-0.1-py3-none-any.whl (3.9 kB)
Collecting watchdog>=2.0
Downloading watchdog-2.1.3-py3-none-manylinux2014_x86_64.whl (75 kB)
Collecting python-dateutil>=2.8.1
Downloading python_dateutil-2.8.1-py2.py3-none-any.whl (227 kB)
Collecting zipp>=0.5
Downloading zipp-3.5.0-py3-none-any.whl (5.7 kB)
Collecting typing-extensions>=3.6.4
Downloading typing_extensions-3.10.0.0-py3-none-any.whl (26 kB)
Collecting pyparsing>=2.0.2
Downloading pyparsing-2.4.7-py2.py3-none-any.whl (67 kB)
Collecting six>=1.5
Downloading six-1.16.0-py2.py3-none-any.whl (11 kB)
Building wheels for collected packages: mock, ghp-import, future
Building wheel for mock (setup.py): started
Building wheel for mock (setup.py): finished with status 'done'
Created wheel for mock: filename=mock-1.0.1-py3-none-any.whl size=23772 sha256=ecc0dc7eb6efdc5f70233fc29fce5f4f940a567cfcb02b520f0a7cf59b57abf7
Stored in directory: /tmp/pip-ephem-wheel-cache-d_w0zttj/wheels/7a/94/b1/0fdc5339a5bd487a5cc15421ec200d9ba3e2aa7190e4a727f1
Building wheel for ghp-import (setup.py): started
Building wheel for ghp-import (setup.py): finished with status 'done'
Created wheel for ghp-import: filename=ghp_import-2.0.1-py3-none-any.whl size=11028 sha256=65be8307c2e39b5d2fa3d7d13e268eb887939ea8916fc9d173b114583435a1e7
Stored in directory: /tmp/pip-ephem-wheel-cache-d_w0zttj/wheels/a3/bf/e1/bd9958bb5e4139097b821a36851d307d590aa2093639e077d9
Building wheel for future (setup.py): started
Building wheel for future (setup.py): finished with status 'done'
Created wheel for future: filename=future-0.18.2-py3-none-any.whl size=491070 sha256=9ac49de9affc229fe4d7deaadfdae24e0aac9d161c9f49011c49b1b875ca6cab
Stored in directory: /tmp/pip-ephem-wheel-cache-d_w0zttj/wheels/56/b0/fe/4410d17b32f1f0c3cf54cdfb2bc04d7b4b8f4ae377e2229ba0
Successfully built mock ghp-import future
Installing collected packages: zipp, urllib3, typing-extensions, six, pytz, pyparsing, MarkupSafe, idna, chardet, certifi, sphinxcontrib-serializinghtml, sphinxcontrib-qthelp, sphinxcontrib-jsmath, sphinxcontrib-htmlhelp, sphinxcontrib-devhelp, sphinxcontrib-applehelp, snowballstemmer, requests, PyYAML, python-dateutil, Pygments, packaging, Jinja2, importlib-metadata, imagesize, future, docutils, babel, alabaster, watchdog, sphinx, pyyaml-env-tag, mergedeep, Markdown, ghp-import, commonmark, click, recommonmark, pillow, mock, mkdocs
Successfully installed Jinja2-3.0.1 Markdown-3.3.4 MarkupSafe-2.0.1 PyYAML-5.4.1 Pygments-2.9.0 alabaster-0.7.12 babel-2.9.1 certifi-2021.5.30 chardet-4.0.0 click-8.0.1 commonmark-0.8.1 docutils-0.17.1 future-0.18.2 ghp-import-2.0.1 idna-2.10 imagesize-1.2.0 importlib-metadata-4.6.1 mergedeep-1.3.4 mkdocs-1.2.1 mock-1.0.1 packaging-21.0 pillow-5.4.1 pyparsing-2.4.7 python-dateutil-2.8.1 pytz-2021.1 pyyaml-env-tag-0.1 recommonmark-0.5.0 requests-2.25.1 six-1.16.0 snowballstemmer-2.1.0 sphinx-4.0.3 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-2.0.0 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.5 typing-extensions-3.10.0.0 urllib3-1.26.6 watchdog-2.1.3 zipp-3.5.0
[rtd-command-info] start-time: 2021-07-08T14:57:16.926864Z, end-time: 2021-07-08T14:57:21.374036Z, duration: 4, exit-code: 0
/home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/bin/python -m pip install --exists-action=w --no-cache-dir -r requirements.txt
Collecting mkdocs==1.1.2
Downloading mkdocs-1.1.2-py3-none-any.whl (6.4 MB)
Collecting tornado>=5.0
Downloading tornado-6.1-cp37-cp37m-manylinux2010_x86_64.whl (428 kB)
Requirement already satisfied: click>=3.3 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from mkdocs==1.1.2->-r requirements.txt (line 1)) (8.0.1)
Requirement already satisfied: PyYAML>=3.10 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from mkdocs==1.1.2->-r requirements.txt (line 1)) (5.4.1)
Requirement already satisfied: Jinja2>=2.10.1 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from mkdocs==1.1.2->-r requirements.txt (line 1)) (3.0.1)
Collecting lunr[languages]==0.5.8
Downloading lunr-0.5.8-py2.py3-none-any.whl (2.3 MB)
Collecting livereload>=2.5.1
Downloading livereload-2.6.3.tar.gz (25 kB)
Requirement already satisfied: Markdown>=3.2.1 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from mkdocs==1.1.2->-r requirements.txt (line 1)) (3.3.4)
Requirement already satisfied: future>=0.16.0 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from lunr[languages]==0.5.8->mkdocs==1.1.2->-r requirements.txt (line 1)) (0.18.2)
Requirement already satisfied: six>=1.11.0 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from lunr[languages]==0.5.8->mkdocs==1.1.2->-r requirements.txt (line 1)) (1.16.0)
Collecting nltk>=3.2.5
Downloading nltk-3.6.2-py3-none-any.whl (1.5 MB)
Requirement already satisfied: importlib-metadata in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from click>=3.3->mkdocs==1.1.2->-r requirements.txt (line 1)) (4.6.1)
Requirement already satisfied: MarkupSafe>=2.0 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from Jinja2>=2.10.1->mkdocs==1.1.2->-r requirements.txt (line 1)) (2.0.1)
Collecting joblib
Downloading joblib-1.0.1-py3-none-any.whl (303 kB)
Collecting regex
Downloading regex-2021.7.6-cp37-cp37m-manylinux2014_x86_64.whl (721 kB)
Collecting tqdm
Downloading tqdm-4.61.2-py2.py3-none-any.whl (76 kB)
Requirement already satisfied: zipp>=0.5 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from importlib-metadata->click>=3.3->mkdocs==1.1.2->-r requirements.txt (line 1)) (3.5.0)
Requirement already satisfied: typing-extensions>=3.6.4 in /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/lib/python3.7/site-packages (from importlib-metadata->click>=3.3->mkdocs==1.1.2->-r requirements.txt (line 1)) (3.10.0.0)
Building wheels for collected packages: livereload
Building wheel for livereload (setup.py): started
Building wheel for livereload (setup.py): finished with status 'done'
Created wheel for livereload: filename=livereload-2.6.3-py2.py3-none-any.whl size=24726 sha256=046c268e06de06a3bd7df1160fe91c8b00e059d7142ed41dd65e85ef9394991a
Stored in directory: /tmp/pip-ephem-wheel-cache-0rrugzep/wheels/d4/f2/03/55f37093eb8cb0c89d7efb206f792dba55cd5bd67b1c5b1ce1
Successfully built livereload
Installing collected packages: tqdm, regex, joblib, tornado, nltk, lunr, livereload, mkdocs
Attempting uninstall: mkdocs
Found existing installation: mkdocs 1.2.1
Uninstalling mkdocs-1.2.1:
Successfully uninstalled mkdocs-1.2.1
Successfully installed joblib-1.0.1 livereload-2.6.3 lunr-0.5.8 mkdocs-1.1.2 nltk-3.6.2 regex-2021.7.6 tornado-6.1 tqdm-4.61.2
[rtd-command-info] start-time: 2021-07-08T14:57:21.824634Z, end-time: 2021-07-08T14:57:21.888143Z, duration: 0, exit-code: 0
git rev-parse HEAD
600a315069246da2bb770304f88cadb6ca3d6426
[rtd-command-info] start-time: 2021-07-08T14:57:22.024845Z, end-time: 2021-07-08T14:57:22.093073Z, duration: 0, exit-code: 0
cat mkdocs.yml
docs_dir: docs
extra_css:
- css/custom.css
- https://assets.readthedocs.org/static/css/badge_only.css
- https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css
extra_javascript:
- readthedocs-data.js
- https://assets.readthedocs.org/static/core/js/readthedocs-doc-embed.js
- https://assets.readthedocs.org/static/javascript/readthedocs-analytics.js
google_analytics: null
markdown_extensions:
- meta
- admonition
- footnotes
- attr_list
- toc
- sane_lists
pages:
- Getting Started:
- Overview: index.md
- What's New?: new.md
- Important Reads: prerequisites.md
- Installation: installation.md
- Support/Bugreport: support.md
- Faceit Create:
- Prepare Geometry: prepare.md
- Setup: setup.md
- Landmarks: landmarks.md
- Rigging: rigging.md
- Expressions: expressions.md
- Bake: bake.md
- Utilities: utils.md
- Export: export.md
- Tips and Tricks: tips.md
- FBX Retargeting: fbx_retargeting.md
- ARKit MOCAP:
- ARKit Overview: arkit_shapes.md
- Setup: arkit_setup.md
- Control Rig: control_rig.md
- Mocap: mocap_utils.md
- Face Cap App: face_cap_utils.md
- Live Link Face: epic_utils.md
- Other:
- Changelog: log.md
- FAQ: FAQ.md
site_author: Fynn Braren
site_description: Faceit - Auto-Rig IPhoneX Shape Keys (Blendshapes) - Performance
Capture for ANY Character!
site_name: Faceit Documentation
site_url: https://faceit-doc.readthedocs.io
theme:
collapse_navigation: true
custom_dir: overrides
include_sidebar: true
name: readthedocs
prev_next_buttons_location: none
sticky_navigation: false
[rtd-command-info] start-time: 2021-07-08T14:57:22.241233Z, end-time: 2021-07-08T14:57:23.269100Z, duration: 1, exit-code: 0
/home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/envs/v2/bin/python -m mkdocs build --clean --site-dir _build/html --config-file mkdocs.yml
WARNING - Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in a future release of MkDocs. Use 'nav' instead.
INFO - Cleaning site directory
INFO - Building documentation to the directory: /home/docs/checkouts/readthedocs.org/user_builds/faceit-doc/checkouts/v2/_build/html
WARNING - Documentation file 'FAQ.md' contains a link to 'hardware.md' which is not found in the documentation files.
WARNING - Documentation file 'epic_utils.md' contains a link to 'img/mocap/epic/epic_ui.jpg' which is not found in the documentation files.
WARNING - Documentation file 'prepare.md' contains a link to 'capture.md' which is not found in the documentation files.
INFO - Documentation built-in 0.48 seconds
经过更多研究后我能够解决这个问题。 失败的原因是因为我没有放置
{% extends "base.html" %}
在 main.html 文件中。
所有必要的信息都可以在这里找到：
https://www.mkdocs.org/user-guide/customizing-your-theme/#using-the-theme-custom_dir
要将任何自定义脚本添加到 Mkdocs 生成的块中，这里是上面答案和 Material/mkdocs 中建议的对我有用的方法：https://squidfunk.github.io/mkdocs-material/customization/#overriding -块
我需要使用marker.io手动安装方法将marker.io小部件集成到我的mkdocs生成的站点，该方法将脚本添加到HEAD标签。
Mkdocs/docs/overrides/ 目录
---main.html---
{% extends "base.html" %}
{% block announce %}
<div class="an_announcement">Some of the announcement that we'd like to show in the theme on all pages.</div>
{% endblock %}
{% block site_meta %}
<!-- Add scripts that need to run before here -->
{{ super() }}
<!-- Add scripts that need to run afterward here -->
<!-- Marker.io feedback tool for Arcana Documentation -->
<script>
window.markerConfig = {
project: '<your marker.io Project ID',
source: 'snippet'
};
</script>
<script>
!function(e,r,a){if(!e.__M.......(window,document);
//snipped marker.io script just to give you the idea
//see https://help.marker.io/en/articles/4667238-widget-installation-methods#h_13f1da8aac for details
</script>
{% endblock %}希望这有帮助！