mkdocs-materialに基づいて実現されたヘルプセンター(markdown+中国語検索+ピクチャ拡大)

需要

駅全体のドキュメントmarkdownを使用して、便利な製品&運営の子供靴たちは

を編纂します

は検索

をサポートする

画像をクリックすると

に拡大できます.
最終的には、左側のナビゲーションバーはマルチレベルのネストをサポートし、右側は現在のドキュメント内のタイトルナビゲーションです.
上部右側の検索バー(現在は分詞検索のみがサポートされており、文全体はサポートされていません):
画像の拡大:
インプリメンテーション
より包括的な情報は公式サイト:mkdocs公式サイトmkdocs-material公式サイトに移動してください.
環境構築
python: 3.7.2

#     
pip install mkdocs mkdocs-material
pip install jieba
#     
mkdocs serve
#   
mkdocs build

パッケージ名
モジュール名
バージョン#バージョン#
mkdocs
mkdocs
1.0.4
mkdocs-material
material
3.0.6
Markdown
markdown
3.0.1
pymdown-extensions
pymdownx
6.0
jieba
jieba
0.39
筆者はmkdocs-material 4.0.1を使用すると大きな穴に遭遇し、バージョン3.0.6のインストールを提案した.
ディレクトリの説明&基本構成
プロジェクトディレクトリは次のとおりです.

assets:カスタムリソース

css

js

syntax:構文の例(無視可能)

img:ドキュメント内のピクチャリソース

を格納する

label:文書内容

index.md:トップページ

mkdocs.yml構成

site_name: '    '
site_author: zzm
site_url: http://xxx.com/help/
#          
site_dir: ../dist/help

#     
nav:
-   : index.md
-           :
  -         : label/user_manual.md
  -         : label/data_desc.md
  -         : label/demand_process.md
-     API  :
  - 0.    :

#       
dev_addr: 127.0.0.1:4050
#     
theme:
  name: material
  language: 'zh'
  favicon: 'assets/favicon.ico'
  logo:
    icon: ' '
  palette:
    primary: 'Light Blue'
    accent: 'Light Blue'
  feature:
    tabs: false
#    css
extra_css:
- 'assets/css/custom.css'
- 'assets/css/simpleLightbox.min.css'
#    js
extra_javascript:
- 'assets/js/jquery-3.2.1.min.js'
- 'assets/js/simpleLightbox.min.js'
- 'assets/js/custom.js'
#     
markdown_extensions:
- markdown.extensions.attr_list
- admonition
- codehilite:
    guess_lang: false
    linenums: false
- toc:
    permalink: true
- footnotes
- meta
- def_list
- pymdownx.arithmatex
- pymdownx.betterem:
    smart_enable: all
- pymdownx.caret
- pymdownx.critic
- pymdownx.details
- pymdownx.inlinehilite
- pymdownx.magiclink
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tasklist
- pymdownx.tilde

中国語検索サポートの追加
現在、ネット上で見つかったチュートリアルはlunrソースコードの置き換えに対して行われていますが、多くは歴史バージョンのソリューションで、lunrの更新に伴い、多くのAPIはすでに面目が異なり、フォルダなどが合わず、ぼんやりしています.ここでは少し新しい案を提供します.もちろん、最終的な解決策はlunrを改造する必要があります.
lunrの動作原理は2つのステップにまとめることができる.

ページの純文字版の内容をjsonファイルに抽出し、アンカー位置、タイトル、記述、および記述に対応する辞書を含む.大体こうなります:

検索ボックスに入力された内容を区切り記号(スペース、句読点など)に基づいて分詞に切り、第1ステップの分詞ライブラリと比較し、対応するアンカーポイントに基づいてページをアドレスする.

中国語検索を実現するのが難しいのは、中国語の分詞のメカニズムが英語とは異なり、区切り記号を簡単に使って語を切ることはできないが、中国語の分詞のアルゴリズムが複雑で、すべてのページ情報を一時的に成分辞書を構築する効率が低いことだ.
英語版のlunrは現在、日本語をサポートしており、「ヘルプドキュメントの概要」については、ヘルプ、ドキュメント、プロフィールの3つの分詞を得ることができます.このメカニズムは,lunr分詞は区切り記号によって導かれるとともに,語長に一定の制限があり,このような漢字が多すぎる成句は,各セグメントに分割された最初の2文字しか保持できない.したがって、検索時には、成文(一般的には2文字より大きい)は現在検索できませんが、スペースで成文にカットして検索することができます.
次のように変更します.

pythonのインストールディレクトリにアクセスしてsearch_を変更index.pyファイル私のディレクトリは/Library/Frameworks/Pythonです.framework/Versions/3.7/lib/python3.7/site-packages/mkdocs/contrib/search/,generate_を修正search_index

    def generate_search_index(self):
        """python to json conversion"""
        page_dicts = {
            'docs': self._entries,
            'config': self.config
        }
        for doc in page_dicts['docs']: #   jieba cut       ，     ，    
            tokens = list(set([token.lower() for token in jieba.cut_for_search(doc['title'].replace('
', ''), True)]))
            if '' in tokens:
                tokens.remove('')
            doc['title_tokens'] = tokens

            tokens = list(set([token.lower() for token in jieba.cut_for_search(doc['text'].replace('
', ''), True)]))
            if '' in tokens:
                tokens.remove('')
            doc['text_tokens'] = tokens

        data = json.dumps(page_dicts, sort_keys=True, separators=(',', ':'), ensure_ascii=False)

        if self.config['prebuild_index']:
            try:
                script_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'prebuild-index.js')
                p = subprocess.Popen(
                    ['node', script_path],
                    stdin=subprocess.PIPE,
                    stdout=subprocess.PIPE,
                    stderr=subprocess.PIPE
                )
                idx, err = p.communicate(data.encode('utf-8'))
                if not err:
                    idx = idx.decode('utf-8') if hasattr(idx, 'decode') else idx
                    page_dicts['index'] = json.loads(idx)
                    data = json.dumps(page_dicts, sort_keys=True, separators=(',', ':'), ensure_ascii=False)
                    log.debug('Pre-built search index created successfully.')
                else:
                    log.warning('Failed to pre-build search index. Error: {}'.format(err))
            except (OSError, IOError, ValueError) as e:
                log.warning('Failed to pre-build search index. Error: {}'.format(e))

        return data

lunr.を修正する.js私のディレクトリ:/Library/frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/mkdocs/contrib/search/templates/search/,検索lunr.Builder.prototype.add置換部分コード

//     15 
lunr.Builder.prototype.add = function (doc, attributes) {
  var docRef = doc[this._ref],
      fields = Object.keys(this._fields)

  this._documents[docRef] = attributes || {}
  this.documentCount += 1

  for (var i = 0; i < fields.length; i++) {
    var fieldName = fields[i],
        extractor = this._fields[fieldName].extractor,
        field = extractor ? extractor(doc) : doc[fieldName],
        tokens = doc[fieldName + '_tokens'],
        terms = this.pipeline.run(tokens),
        fieldRef = new lunr.FieldRef (docRef, fieldName),
        fieldTerms = Object.create(null)

もう一部置換する必要があります

lunr.trimmer = function (token) {
  return token.update(function (s) {
    return s.replace(/^\s+/, '').replace(/\s+$/, '')
  })
}

できました～今中国語を入力して検索できない問題は解決しました
画像をクリックして拡大
画像の拡大はLightboxとも呼ばれ、主にページ上のサムネイルの大図版を表示するためのフローティングウィンドウを提供しています.もう1つはzoom-inと呼ばれ、主にマウスのサスペンションを実現する際に拡大鏡が現れる.現在markdownで使用するには外部からしか導入できません.
まずcssとjsをダウンロードして導入します:Simple lightbox

|---assets
|   |---css
|   |   |----simpleLightbox.min.css
|   |   `----custom.css
|   `---js
|       |----simpleLightbox.min.js
|       `----custom.js

次に、プロファイルmkdocs.ymlでextra_を設定するcssとextra_JAvascript(前文の構成など);次はcustomでcssとcustom.jsにそれぞれ追加:

/* custom.css */
a.boxedThumb {
  display: block;
  padding: 4px;
  line-height: 20px;
  border: 1px solid #ddd;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  border-radius: 4px;
  -webkit-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.055);
  -moz-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.055);
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.055);
  -webkit-transition: -webkit-transform .15s ease;
  -moz-transition: -moz-transform .15s ease;
  -o-transition: -o-transform .15s ease;
  -ms-transition: -ms-transform .15s ease;
  transition: transform .15s ease;
}

a.boxedThumb:hover {
  -webkit-transform: scale(1.05);
  -moz-transform: scale(1.05);
  -o-transform: scale(1.05);
  -ms-transform: scale(1.05);
  transform: scale(1.05);
  z-index: 5;
}

$(document).ready(function () {
  let productImageGroups = []
  $('.img-fluid').each(function () {
    let productImageSource = $(this).attr('src')
    let productImageTag = $(this).attr('tag')
    let productImageTitle = $(this).attr('title')
    if (productImageTitle) {
      productImageTitle = 'title="' + productImageTitle + '" '
    }
    else {
      productImageTitle = ''
    }
    $(this).
        wrap('')
    productImageGroups.push('.' + productImageTag)
  })
  jQuery.unique(productImageGroups)
  productImageGroups.forEach(productImageGroupsSet)

  function productImageGroupsSet (value) {
    $(value).simpleLightbox()
  }
})

注意:ここでは、MarkDownリンク/ピクチャの後に任意のラベルのフィールドをカッコで示すことができるプラグインがオンになっていることを確認します.

markdown_extensions:
  - markdown.extensions.attr_list

使用時

![   ](./../img/user_manual_1.png){.img-fluid tag=1}
#      
![   ](./../img/user_manual_1.png){.img-fluid tag=2 title="    "}
#    
![   ](./../img/user_manual_1.png){.img-fluid tag=3}
![   ](./../img/user_manual_1.png){.img-fluid tag=3}
![   ](./../img/user_manual_1.png){.img-fluid tag=3}

～を済ませる