docsify一个神奇的文档站点生成器

开源精选》是我们分享Github、Gitee等开源社区中优质项目的栏目，包括技术、学习、实用与各种有趣的内容。本期推荐的docsify 即时生成您的文档网站。与 GitBook 不同的是，它不会生成静态 html 文件。相反，它会巧妙地加载和解析您的 Markdown 文件并将它们显示为网站。

特征

没有静态构建的 html 文件
简单轻便
智能全文搜索插件
多个主题
有用的插件 API
表情符号支持
兼容IE11
支持服务端渲染

快速开始

建议docsify-cli全局安装，有助于在本地初始化和预览网站。

npm i docsify-cli -g在子目录init中

初始化

如果要在./docs子目录下编写文档，可以使用init命令。

docsify init ./docs

写作内容

完成后，您可以在子目录init中看到文件列表。./docs

index.html作为入口文件
README.md作为主页
.nojekyll防止 GitHub Pages 忽略以下划线开头的文件

您可以轻松地更新文档中的内容./docs/README.md，当然您也可以添加更多页面。

预览您的网站

使用运行本地服务器docsify serve。您可以在浏览器上预览您的网站http://localhost:3000。

docsify serve docs

手动初始化

如果您不喜欢npm或无法安装该工具，您可以手动创建index.html：

<!-- index.html -->

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" />
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify={
      //...
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
</body>
</html>

指定 docsify 版本

v4.x.x请注意，在以下两个示例中，当发布新的 docsify 主要版本时（例如=> v5.x.x），需要手动更新 docsify URL 。定期检查 docsify 网站以查看是否发布了新的主要版本。

在 URL ( ) 中指定主要版本@4将允许您的站点自动接收非破坏性增强（即“次要”更新）和错误修复（即“补丁”更新）。这是加载 docsify 资源的推荐方式。

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" />
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>

如果您希望将 docsify 锁定到特定版本，请@在 URL 中的符号后面指定完整版本。这是确保您的网站外观和行为方式相同的最安全方法，无论对未来版本的 docsify 进行任何更改。

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4.11.4/themes/vue.css">
<script src="//cdn.jsdelivr.net/npm/docsify@4.11.4"></script>

手动预览您的网站

如果您的系统上安装了 Python，您可以轻松地使用它来运行静态服务器来预览您的站点。

cd docs && python -m SimpleHTTPServer 3000

cd docs && python -m http.server 3000

加载对话框

如果你愿意，你可以在 docsify 开始渲染你的文档之前显示一个加载对话框：

<!-- index.html -->

<div id="app">Please wait...</div>

如果你改变了，你应该设置data-app属性el：

<!-- index.html -->

<div data-app id="main">Please wait...</div>

  <script>
    window.$docsify={
      el: '#main'
    }
  </script>

配置

window.$docsify您可以通过定义为对象来配置 Docsify ：

<script>
  window.$docsify={
    repo: 'docsifyjs/docsify',
    maxLevel: 3,
    coverpage: true,
  };
</script>

配置也可以定义为一个函数，在这种情况下，第一个参数是 Docsifyvm实例。该函数应返回一个配置对象。vm这对于在诸如降价配置之类的地方进行引用很有用：

<script>
  window.$docsify=function(vm) {
    return {
      markdown: {
        renderer: {
          code(code, lang) {
            // ... use `vm` ...
          },
        },
      },
    };
  };
</script>

加载导航栏

类型：Boolean|String
默认：false

_navbar.md如果为true则从 Markdown 文件加载导航栏，否则从指定的路径加载它。

window.$docsify={
  // load from _navbar.md
  loadNavbar: true,

  // load from nav.md
  loadNavbar: 'nav.md',
};

加载侧边栏

类型：Boolean|String
默认：false

_sidebar.md如果为true则从 Markdown 文件加载侧边栏，否则从指定的路径加载它。

window.$docsify={
  // load from _sidebar.md
  loadSidebar: true,

  // load from summary.md
  loadSidebar: 'summary.md',
};

隐藏侧边栏

类型：Boolean
默认：true

此选项将完全隐藏您的侧边栏，并且不会在侧面呈现任何内容。

window.$docsify={
  hideSidebar: true,
};

主页

类型：String
默认：README.md

README.md在您的 docs 文件夹中将被视为您网站的主页，但有时您可能需要提供另一个文件作为您的主页。

window.$docsify={
  // Change to /home.md
  homepage: 'home.md',

  // Or use the readme in your repo
  homepage:
    'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};

如果您在侧边栏中有指向主页的链接，并希望在访问根 url 时将其显示为活动状态，请确保相应地更新侧边栏：

- Sidebar
  - [Home](/)
  - [Another page](another.md)

主题

有一些可用的主题，包括官方和社区制作的。复制Vue和buble网站自定义主题以及@liril-net贡献的黑色风格主题。

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />

压缩文件在/lib/themes/.

<!-- compressed -->

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/buble.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dark.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/pure.css" />

如果您有任何想法或想要开发新主题，欢迎您提交pull request。

GitHub 页面

有三个地方可以为您的 GitHub 存储库填充文档：

docs/文件夹
主分支
gh-pages 分支

建议您将文件保存到存储库分支的./docs子文件夹中。master然后master branch /docs folder在存储库的设置页面中选择作为 GitHub Pages 源。

GitLab 页面

如果要部署 master 分支，请.gitlab-ci.yml使用以下脚本创建一个：

.public解决方法是cp不会在无限循环中复制到public/自身。

pages:
  stage: deploy
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    - public
  only:
  - master

—END—

开源协议：MIT license

开源地址：https://github.com/docsifyjs/docsify

在的网站效果多样而功能复杂，技术栈也多种多样，react\vue\jquery等层出不穷，对于编程爱好者初学者入门极不友好。我这里有一个简单的个人网站模板，包括主页、项目和联系方式、关于我四个部分。你可以根据自己的需求进行调整。

模板效果展示：

主页 (index.html)

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>我的个人网站</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <header>
        <nav>
            <ul>
                <li><a href="index.html">主页</a></li>
                <li><a href="about.html">关于我</a></li>
                <li><a href="projects.html">项目</a></li>
                <li><a href="contact.html">联系方式</a></li>
            </ul>
        </nav>
    </header>
    <main>
        <section class="hero">
            <h1>欢迎来到我的个人网站</h1>
            <p>我是一个充满激情的程序员，热衷于学习和分享知识。</p>
        </section>
    </main>
    <footer>
        <p>? 2024 我的名字</p>
    </footer>
</body>
</html>

关于我 (about.html)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>关于我 - 我的个人网站</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
<header>
  <nav>
    <ul>
      <li><a href="index.html">主页</a></li>
      <li><a href="about.html">关于我</a></li>
      <li><a href="projects.html">项目</a></li>
      <li><a href="contact.html">联系方式</a></li>
    </ul>
  </nav>
</header>
<main>
  <section class="about">
    <h1>关于我</h1>
    <p>你好！我是[一周一志程序员]，一名经验丰富的Java程序员，致力于能源电力SaaS和系统架构设计。</p>
    <p>目前我正在备考2024年11月6日的《系统架构设计师》考试，并在着手成为独立开发者，轻创业准备中。</p>
  </section>
</main>
<footer>
  <p>? 2024 一周一志程序员</p>
</footer>
</body>
</html>

项目 (projects.html)

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>项目 - 我的个人网站</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <header>
        <nav>
            <ul>
                <li><a href="index.html">主页</a></li>
                <li><a href="about.html">关于我</a></li>
                <li><a href="projects.html">项目</a></li>
                <li><a href="contact.html">联系方式</a></li>
            </ul>
        </nav>
    </header>
    <main>
        <section class="projects">
            <h1>项目</h1>
            <ul>
                <li><strong>电力SaaS平台开发</strong> - 开发用电考核模块。</li>
                <li><strong>系统架构设计</strong> - 为不同客户提供系统架构解决方案。</li>
                <li><strong>Spring Boot 项目</strong> - 创建和管理多个Spring Boot项目。</li>
            </ul>
        </section>
    </main>
    <footer>
        <p>? 2024 我的名字</p>
    </footer>
</body>
</html>

联系方式 (contact.html)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>联系方式 - 我的个人网站</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
<header>
  <nav>
    <ul>
      <li><a href="index.html">主页</a></li>
      <li><a href="about.html">关于我</a></li>
      <li><a href="projects.html">项目</a></li>
      <li><a href="contact.html">联系方式</a></li>
    </ul>
  </nav>
</header>
<main>
  <section class="contact">
    <h1>联系方式</h1>
    <p>如果你有任何问题或合作意向，请随时联系我。</p>
    <p>Email: <a href="mailto:1184795629@qq.com">your-email@domain.com</a></p>
    <p>公众号: <a href="#">一周一志程序员</a></p>
    <p>抖音: <a href="#">麦冬会开花</a></p>
  </section>
</main>
<footer>
  <p>? 2024 我的名字</p>
</footer>
</body>
</html>

样式文件 (styles.css)

body {
    font-family: Arial, sans-serif;
    line-height: 1.6;
    margin: 0;
    padding: 0;
}

header {
    background: #06362B;
    color: #fff;
    padding: 1rem 0;
}

nav ul {
    list-style: none;
    padding: 0;
}

nav ul li {
    display: inline;
    margin-right: 1rem;
}

nav ul li a {
    color: #fff;
    text-decoration: none;
}

.hero {
    background: #f4f4f4;
    padding: 2rem;
    text-align: center;
}

.about, .projects, .contact {
    padding: 2rem;
}

footer {
    background: #06362B;
    color: #fff;
    text-align: center;
    padding: 1rem 0;
    position: fixed;
    width: 100%;
    bottom: 0;
}

你可以将这些文件保存为index.html、about.html、projects.html、contact.html和styles.css，并将它们放在同一目录下。然后，你可以通过浏览器打开index.html来查看你的个人网站。

学习使用，希望这对你有帮助把！如果你有其他需求或需要进一步定制，请告诉我。

者：HelloGitHub-追梦人物

HTTP 报文以明文形式传输，如果你的网站只支持 HTTP 协议，那么就有可能遭受到安全攻击。你可以使用 Google 浏览器打开一个 HTTP 协议网站，会发现 Chrome 在网址的左边将这个网站标记为不安全。

HTTPS 为 HTTP 报文提供了一个加密传输的通道，这样攻击者就无法窃听或者篡改传输的内容。要启用 HTTPS，必须向一个可信任机构申请一个 HTTPS 证书。专业的证书申请需要收费，不过对于个人博客网站来说，有很多免费的证书申请机构。比如 Let’s Encrypt，它提供了免费的证书申请服务，申请过程十分简单，只需要运行几条命令即可，而且证书到期后支持自动续期，可谓一劳永逸。接下来我们就是用 Let’s Encrypt 提供的工具来申请免费的 HTTPS 证书。

首先安装 Let’s Encrypt 提供的证书申请工具。登录 https://certbot.eff.org/ 选择我们博客网站使用的服务器软件和操作系统。教程中以 Nginx 和 CentOS 7 为例：

首先安装必要工具：

$ sudo yum -y install yum-utils
$ sudo sudo yum install -y certbot python2-certbot-nginx

certbot python2-certbot-nginx 是 Let’s Encrypt 提供的 HTTPS 证书申请的工具，python2-certbot-nginx 是专门针对 Nginx 的插件，使得 Nginx 运行的服务申请证书更加简单方便。

然后运行证书申请命令：

$ sudo certbot --nginx

注意
经测试，运行上述命令后有可能报 ImportError: No module named 'requests.packages.urllib3' 的错误，这是由于 requests 和 urlib3 版本过低所致（可以参考这个 issue[2] 的讨论），解决办法是重装它们，运行下面的命令：

$ pip uninstall requests
$ pip uninstall urllib3
$ yum remove python-urllib3
$ yum remove python-requests

然后重新安装 certbot，由于它依赖上面两个包，所以重装时会一并装上：

$ sudo yum install -y certbot python2-certbot-nginx

重新执行证书申请命令：sudo certbot --nginx

会有一系列交互式的提示，首先会让你输入邮箱，用于订阅。然后输入 a 同意他们的政策。

接着 certbot 会自动扫描出来域名，根据提示输入想开启 HTTPS 的域名标号：

Which names would you like to activate HTTPS for

1: django-blog-tutorial-v2-demo.zmrenwu.com

Select the appropriate numbers separated by commas and/or spaces, or leave input
blank to select all options shown (Enter 'c' to cancel): 1

然后 certbot 会做一个域名校验，证明你对这个域名有控制权限。验证通过后，Let's Encrypt 就会把证书颁发给你。

最后会提示你是否把 HTTP 重定向到 HTTPS，当然选择是，这样 certbot 会自动帮我们修改 Nginx 的配置，将 HTTP 重定向到 HTTPS，如果用户使用 HTTP 协议访问我们的博客网站，就会重定向到 HTTPS 协议访问，确保安全性。

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.

1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.

Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
Redirecting all traffic on port 80 to ssl in /etc/nginx/conf.d/django-blog-tutorial-v2.conf

certbot 申请的证书只有 3 个月有效期，不过没有关系，certbot 可以无限续期，我们增加一条 crontab 定时任务用来执行 certbot 自动续期任务，这样一次申请，终生使用。

打开 /etc/crontab，增加定时任务：

echo "0 0,12 * * * root python -c 'import random; import time; time.sleep(random.random() * 3600)' && certbot renew" | sudo tee -a /etc/crontab > /dev/null

这里配置每天 12 点执行自动续期命令。

由于全站开启了 HTTPS，因此需要把网站中非 HTTPS 的内容（比如通过 HTTP 协议请求的外部资源）改为 HTTPS，我们的博客中目前有一处引入外部图标库的样式文件是以 HTTP 协议引入的，需要改为 HTTPS：

base.html
?
<link rel="stylesheet" href="https://code.ionicframework.com/ionicons/2.0.1/css/ionicons.min.css">

以上，简单几步，就开启了全站 HTTPS。

参考资料

[1]HelloGitHub-Team 仓库: https://github.com/HelloGitHub-Team/HelloDjango-blog-tutorial

[2]issue: https://github.com/certbot/certbot/issues/5104

『讲解开源项目系列』——让对开源项目感兴趣的人不再畏惧、让开源项目的发起者不再孤单。跟着我们的文章，你会发现编程的乐趣、使用和发现参与开源项目如此简单。欢迎留言联系我们、加入我们，让更多人爱上开源、贡献开源～

在线咨询

上一篇：java 如何解析网页？
下一篇：2017开启新历程：H5游戏开发-白鹭时代

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

整合营销服务商