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" >

以上，簡單幾步，就開啟了全站 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小時內與您取得聯系。

整合營銷服務商