(四)MkDocs学习——自定义主题
mkdocs学习笔记系列
- (一)MkDocs 学习——快速开始
- (二)MkDocs学习笔记——撰写文档
- (三)MkDocs学习——配置主题
- (四)MkDocs学习——自定义主题
- (五)MkDocs学习——配置文件
- (六)MkDocs学习——部署文档
- (七)mkdocs学习——其他技巧
如果您想对现有主题进行一些调整,则无需从头开始创建自己的主题。对于只需要一些CSS和(或)JavaScript的小调整,您可以使用docs_dir。但是,对于更复杂的自定义(包括覆盖模板),您需要使用主题的custom_dir设置。
使用docs_dir
extra_css和extra_javascript配置选项可用于对现有主题进行调整和自定义。要使用它们,您只需要在[文档目录]中包含CSS或JavaScript文件。
例如,要更改文档中标题的颜色,请创建一个名为extra.css
的文件,并将其放在文档Markdown旁边。 在该文件中添加以下CSS。
h1 {color: red;
}
Note
如果您使用ReadTheDocs部署文档。 您需要明确列出要包含在配置中的CSS和JavaScript文件。为此,请将以下内容添加到mkdocs.yml中。
extra_css: [extra.css]
在进行这些更改之后,当你运行mkdocs serve
后将能看到效果。运行该命令后将会,CSS所做的改变将自动更新。
Note
在页面内容之后,任何额外的CSS或JavaScript文件都将添加到生成的HTML文档中。如果您希望包含JavaScript库,则可以通过使用主题的custom_dir获得更好支持。
使用主题的custom_dir
主题的custom_dir配置选项可用于指向覆盖父主题目录中的文件。父主题将是主题中name配置选项定义的主题。 custom_dir
中与父主题中的文件同名的任何文件都将替换父主题中同名文件。custom_dir
中的任何其他文件都将添加到父主题中。 custom_dir
的内容应该镜像父主题的目录结构。您可以包含模板,JavaScript文件,CSS文件,图像,字体或主题中包含的任何其他媒体文件。
Note
为此,主题的name
设置必须设置为已知的已安装主题。 如果name
设置被设置为null
(或未定义[custom theme])。
例如,mkdocs主题([查看源代码])包含以下目录结构(部分):
- css\
- fonts\
- img\- favicon.ico- grid.png
- js\
- 404.html
- base.html
- content.html
- nav-sub.html
- nav.html
- toc.html
要覆盖该主题中包含的任何文件,请在docs_dir
旁边创建一个新目录:
mkdir custom_theme
然后将您的mkdocs.yml
配置文件指向新目录:
theme:name: mkdocscustom_dir: custom_theme/
要覆盖404错误页面(“找不到文件”),请将名为404.html
的新模板文件添加到custom_theme
目录中。 有关可以包含在模板中的内容的信息,请查看用于构建自定义主题的文档。
要覆盖favicon,您可以在custom_theme/img/favicon.ico
中添加一个新的图标文件。
要包含JavaScript库,请将库复制到custom_theme/js/
目录。
您的目录结构现在应如下所示:
- docs/- index.html
- custom_theme/- img/- favicon.ico- js/- somelib.js- 404.html
- config.yml
Note
父主题中包含的(在name
中定义)但不包括在custom_dir
中的任何文件将继续使用。custom_dir
只会覆盖/替换父主题中的文件。 如果要删除文件或从头开始构建主题,则应查看用于构建自定义主题的文档。
覆盖模板块
内置主题在模板块中实现了许多部分,可以在main.html
模板中单独覆盖。 只需在custom_dir
中创建一个main.html
模板文件,并在该文件中定义替换块。 只要确保main.html
扩展base.html
。 例如,要更改MkDocs主题的标题,替换的main.html
模板将包含以下内容:
{% extends "base.html" %}{% block htmltitle %}
<title>Custom title goes here</title>
{% endblock %}
在上面的例子中,将使用自定义main.html
文件中定义的htmltitle
块代替父主题中定义的默认htmltitle
块。 您可以根据需要重新定义任意数量的块,只要这些块在父级中定义即可。 例如,您可以将Google Analytics脚本替换为不同服务的脚本,或者将搜索功能替换为您自己的搜索功能。 您需要查询正在使用的父主题,以确定可以覆盖的块。 MkDocs和ReadTheDocs主题提供以下块:
site_meta
:包含文档头中的元标记。htmltitle
:包含文档头中的页面标题。styles
:包含样式表的链接标记。libs
:包含页眉中包含的JavaScript库(jQuery等)。scripts
:包含应在页面加载后执行的JavaScript脚本。analytics
:包含分析脚本。extrahead
:<head>
中的空块,用于插入自定义标记/脚本/等。site_name
:包含导航栏中的站点名称。site_nav
:包含导航栏中的站点导航。search_box
:包含导航栏中的搜索框。next_prev
:包含导航栏中的下一个和上一个按钮。repo
:包含导航栏中的GitHub存储库链接。content
:包含页面的页面内容和目录。footer
:包含页脚。
您可能需要查看源模板文件,以确保您的修改将适用于站点的结构。 有关可在自定义块中使用的变量列表,请参见[模板变量]。 有关块的更完整说明,请参阅[Jinja文档]。
组合custom_dir和模板块
将JavaScript库添加到custom_dir
将使其可用,但不会将其包含在MkDocs生成的页面中。因此,需要从HTML添加链接到库。
启动上面的目录结构(截断):
- docs/
- custom_theme/- js/- somelib.js
- config.yml
一个指向custom_theme/js/somelib.js
文件的链接需要添加到模板中。 由于somelib.js
是一个JavaScript库,它在逻辑上会进入libs
块。 但是,仅包含新脚本的新libs
块将替换父模板中定义的块,并且将删除父模板中库的任何链接。 为了避免破坏模板,可以使用super block从块中调用super
:
{% extends "base.html" %}{% block libs %}{{ super() }}<script src="{{ base_url }}/js/somelib.js"></script>
{% endblock %}
请注意,base_url模板变量用于确保链接始终相对于当前页面。
现在生成的页面将包含指向模板提供的库的链接以及custom_dir
中包含的库。custom_dir
中包含的任何其他CSS文件也是如此。
(四)MkDocs学习——自定义主题相关推荐
- (三)MkDocs学习——配置主题
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- Android进阶学习-自定义主题(3)
效果图,略骚,不要笑!!! 我们使用的是这么一张图片,图片是静态的,我们通过旋转动画去实现加载的效果. 首先我们看下,一个加载窗口需要些什么.一个ImageVIew和一个TextView,那么我们就有 ...
- (一)MkDocs 学习——快速开始
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- (五)MkDocs学习——配置文件
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- (二)MkDocs学习笔记——撰写文档
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- (六)MkDocs学习——部署文档
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- 2022-04-05 学习记录--React-React UI组件库-ant-design(蚂蚁金服)—— 按需引入样式 + 自定义主题
一.流行的开源React UI组件库 流行的开源React UI组件库 material-ui(国外) 1.官网:http://www.material-ui.com/#/ 2.github:http ...
- ExtJS4.2:自定义主题 入门
背景 用过 ExtJs 的朋友都有一种趋势:审美疲劳,好在 Ext4.1 之后的版本提供了快速自定义主题的功能,本文的内容主要来自:http://docs.sencha.com/extjs/4.2.2 ...
- 彰显个性│博客园的自定义主题
目录预览 一.开放的博客园 二.主题推荐 三.自定义主题配置CSS 四.自定义主题配置JS 五.页面加载loading 六.页面看板 七.动态背景 八.标签动效 一.开放的博客园 在国内,开源社区有很 ...
最新文章
- 润乾设计器连接数据源,ie预览问题
- 微信小程序,你的场景呢?
- 【CentOS Linux 7】【gcc编译器】
- 史上最详细 DevC++无法运行正则表达式
- 词法分析器java_Java代码到底是如何编译成机器指令的。
- 什么叫诚实_他爱不爱你,身体最诚实
- CodeForces 688B - Lovely Palindromes(思路)
- 11content_processor
- 文件粉碎机c语言代码,Life——文件粉碎机源码
- numpy 索引,切片 ,转置,变值,多个数组的拼接
- 亿级规模的Feed流推荐系统,如何轻松设计?
- sim卡没坏但苹果手机无服务_iPhone手机无服务那些事儿
- php7 捕获语法错误,PHP7 method_exists未捕获错误:函数名称必须是字符串
- 协议栈处理中的conntrack HASH查找/Bloom过滤/CACHE查找/大包与小包/分层处理风格
- 抖音算法暑期实习春招双双发车
- idea怎么创建python项目
- 基于php014居民小区物业管理系统
- 最近抖音,小红书上面有个很火的天气推送的公众号,可以给自己爱的人进行定时推送. 效果如下,结合亲生经历给大家讲述一下操作流程。整个项目代码目前十分规整,项目代码整体400多行 ,就直接分享出来吧.
- 汉字Unicode 编码大全
- linux电脑滚轮不能用,图文详解电脑鼠标滚轮不动了怎么办_电脑鼠标滚轮不能用的三种解决方法-系统城...
热门文章
- 并发执行变成串行_一篇讲透如何理解数据库并发控制
- php循环奇,php – javascript循环奇/偶数组
- EduSoho教育周报(0729-0804
- 关于成功的微信营销案例 转载
- CSS媒体查询@media (prefers-color-scheme:dark)判断系统白天黑夜模式
- 从500亿缩水到167亿!自动驾驶芯片第一股“流血上市”
- 企业文档加密软件选择标准是什么
- 咦,Oreo怎么收不到广播了?
- 2021年劳务员-通用基础(劳务员)考试题及劳务员-通用基础(劳务员)考试资料
- Wex5访问自驾PhP服务,WeX5经过Baas服务访问数据库