海南做网站,宠物网站建设的目的,wordpress统计访问ip,php做的购物网站代码给大家安利如何快速搭建个人博客网站#xff01; 前言 这是我本地运行的一个使用sphinx构建的博客服务#xff0c;这些文章#xff0c;都是用markdown写的。
一直有个想法#xff0c;就是把自己写的这些文件#xff0c;搞成一个博客网站#xff0c;放到网上#xff0c… 给大家安利如何快速搭建个人博客网站 前言 这是我本地运行的一个使用sphinx构建的博客服务这些文章都是用markdown写的。
一直有个想法就是把自己写的这些文件搞成一个博客网站放到网上但是一想要搞个域名、一个服务器这样长期运营维护成本有些高。再一个个人技术博客独立地址百度中抓取率可能也不高结果就是花了大成本结果自嗨别人搜索、访问不到所以一直没有行动。
最近发现用 gitee sphinx readthedocs 可以低学习成本免资金投入长期运营。今天就来把这个技术分享给大家。
解决方案介绍
gitee是国内免费的代码托管平台相比github在国内有更快的访问速度全中文界面对国人更友好。
sphinx是一个功能强大的文档生成器具有许多用于编写技术文档的强大功能。
readthedocs是一个免费在线文档托管范围平台可以使用二级域名显示个人博客。
具体操作 Ⅰ、首先在gitee上创建一个开源项目 Ⅱ、下载项目并配置python3环境 建议使用虚拟运行环境 Ⅲ、安装sphinx 在虚拟环境中安装sphinx pip install sphinx **如果想在本地调试运行查看效果需要安装sphinx-autobuild pip install autobuild安装docutils pip install docutils如果自己使用的markdown编写的文档需要安装myst-parser pip install myst-parser环境安装好之后可以使用 sphinx-quickstart . 创建项目架构 项目创建好之后会在当前路径下生成如下文件结构 项目名称
|————build
|————makde.bat
|————Makefile
|————source|————_static|————_templates|————conf.py|————index.rst build文件夹 生成的文件的输出目录 source文件夹 存放文档源文件 _static文件夹 静态文件目录 _template文件夹 模板目录 conf.py文件 进行sphinx配置的文件 index.rst文件 文档项目的起始文件用于配置整个项目文档结构 make.bat文件 Windows命令行中编译用的脚本 Makefile文件 编译脚本make命令使用 Ⅳ、修改配置文件 修改index.rst文件一级目录
.. toctree:::maxdepth: 2文档名称或rst文件路径rst文件中在双下划线或单下划线 上面一行的是一级目录空行“.. toctree::” 这是一个固定写法代表这是目录树根“:maxdepth: 2” 代表下面下面文档在目录树中显示几级目录空行你的文档名称(不带后缀)或者rst文件路径(不带后缀)不能顶行写要与上面的“:maxdepth:”起始位置对齐。 如果你想做出分类的效果上面这个模板可以再复制粘贴到文件下面。如下图 修改conf.py文件 这是项目的一个重要配置文件具体配置参数可以安装官方帮助来。如下图 在这个配置文件中“html_theme”可以配置HTML的主题样式默认是‘alabaster’如果觉得这个主题样式自己不喜欢可以去找自己喜欢的主题样式然后根据主题样式的帮助文档使用主题。 Ⅴ、用markdown编写文档 用markdown的编辑器编写你自己的md文档。把写好的md文件放到项目的source文件夹下再编辑index.rst文件在文件中添加md文件名称。这种方式很简单、快捷。但是一旦md文件多了管理上就会有诸多不便。也可以在source文件夹下自己创建文件夹把md文件丢在自己建的文件夹中分类管理md文件中有图片也可以在md同级建文件夹管理图片然后在index.rst文件中添加“文件夹名/md文件名”这种方式添加文件或者在新建的文件夹下再新建一个rst文件安装文章图1中的配置写法管理。 Ⅵ、本地测试(可选) 这个步骤不是必须的但是建议还是本地测试一下测试通过了才正式用readthedocs来发布。安装sphinx-autobuild pip install sphinx-autobuild执行 sphinix-autobuild.exe .\source\ .\build\html windows系统 这样就会自动编译。编译通过可以通过http://127.0.0.1:8000 来访问看下效果。 如果觉得是界面效果不满意可以去更换主题。 Ⅶ、在readthedocs上导入项目 在导入readthedocs之前需要把项目中安装的库生成到requirements.txt文件中。如 下面是requirements.txt文件中的内容
sphinx
docutils
myst-parser上传已经通过自己验证之后的项目文件到gitee。build文件夹下的内容可以不用上传。github也是类似访问 www.readthedocs.org 网站注册一个账户登录点击【导入一个项目】 【手动导入】填写项目名称、gitee的项目路径(不带.git)、默认分支(master) 注意 这个项目名称将作为博客访问的readthedocs的二级域名为了好记住用英文不要太长与gitee上的项目名称没有关系可以不同名。在readthedocs中找到自己导入的项目的【构建】点击【构建版本】此时就会开始构建。 注意 readthedocs默认配置构建项目时会构建sphinx-HTML、PDF、EPUB 三种如果你项目中的文档、图片较少构建这三个没有问题。但是如果你项目文档、图片都比较大可能会报错可以在readthedocs项目的【管理】 高级设置 中取消 PDF、EPUB的构建。注意 因为readthedocs也是国外服务在国内可能也会出现访问慢或无法访问、或没有及时更新博客界面情况只要构建成功24小时后再访问。
