我希望在共享指向我的 mkdocs 文档的链接时进行图像预览，该文档由 RTD 托管和构建。我需要覆盖站点的 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