FSWikiから GitLab Pages と HonKit に載せ替えた話

この記事は、Wano Group Advent Calendarの12日目の記事です。

前置き

社内にはかなりたくさんのドキュメントがあるのですが、FSWikiという、とても年季のはいったシステムで動いていました。
変えたいよねーという話は幾数年前から言われてきたのですが、代替するものとして決定打にかけて放置されてました(単に忙しかっただけかもしれない)。
今回、意を決してGitLab Pagesに載せ替えました。

載せ替え候補にあがったもの

検討した載せ替え候補とやめた理由を雑に書いておきます。

• GitLab Wiki ... 一覧性が悪い。
• Notion ... 気軽に壊せすぎる。PlantUML使えない。
• Docbase ... 階層構造不可
• Confluence ... 重い

他にも色々検討したものの、すべて帯に短しタスキに長しだし、お金払わないといけないし...といことで、最終的に静的なページでいいので、Gitlab Pages でいいやということになり、静的サイトジェネレーターとして、HonKitを選びました。

HonKitとは？

HonKit とは、GitBook から fork されたプロジェクトです。
GitBook は更新が止まってしまっている(非公開になった)ので、古いnodejsでしか動きませんでしたが、HonKitは最近のnodejsでも動きます。GitBook よりも build が速く、GitBook の plugin も使えます(だいたい)。

詳しくは、下記に書かれています。
https://efcl.info/2020/06/19/githon/

前提

GitLabですが、社内のサーバでDockerで動かしています。nginx もDockerで動いています。

GitLab Pages の設定

/etc/gitlab/gitlab.rb には、下記のような設定を追加します。

pages_external_url 'https://pages.exapmle.com'
gitlab_pages['inplace_chroot'] = true
gitlab_pages['enable'] = true
gitlab_pages['nginx'] = true
gitlab_pages['dir'] = "/var/opt/gitlab/gitlab-pages"
gitlab_pages['log_directory'] = "/var/log/gitlab/gitlab-pages"
gitlab_pages['external_https'] = [':81']
gitlab_pages['access_control'] = false

nginx の設定(適当にしてもらったら良いですが)

server {
    listen 443 ssl;
    server_name example.com *.pages.example.com, pages.example.com;

    ssl_certificate     証明書のpath;
    ssl_certificate_key 鍵のpath;

    location / {
        set $proxy_port 41080; # 41080 => docker 80
        if ($http_x_forwarded_host ~ '(.+\.)?pages\.example.com$') {
          set $proxy_port 41081; # 41081 => docker 81
        }

        proxy_set_header Host $http_x_forwarded_host;
        proxy_pass https://IPアドレス:$proxy_port;
    }
}

.gitlab-ci.yml

image: node:14

# add 'node_modules' to cache for speeding up builds
cache:
  paths:
    - node_modules/ # Node modules and dependencies

before_script:
  - apt update -y 
  - apt install -y default-jre fonts-ipafont fonts-ipaexfont graphviz locales
  # 履歴をだすpluginで日本語を表示したいので
  - git config --local core.quotepath false
  # PlantUMLの吐き出す画像で日本語が表示出来ない問題に対応
  - sed -i -E 's/# (ja_JP.UTF-8)/\1/' /etc/locale.gen
  - locale-gen ja_JP.UTF-8
  - update-locale LANG=ja_JP.UTF-8
  - export LANG=ja_JP.UTF-8
  # ある日突然必要になったので追加した
  - npm config set unsafe-perm true
  # honkit の pluginをインストール
  - npm install -g honkit gitbook-summary gitbook-plugin-{intopic-toc,collapsible-chapters,hints,advanced-emoji,graph,edit-link,git-author,hide-published-with,changelog,uml,back-to-top-button,copy-code-button,custom-js-css,comments-footer,insert-logo,search-pro-fixed,recently-updated} honkit-plugin-todo
  # SUMMARY.md を作るコマンド(↑のgitbook-summary)
  - book sm -i 'node_modules' -s '_' -t 'Title'

test:
  stage: test
  script:
    - honkit build . public # build to public path
  only:
    - branches # this job will affect every branch except 'master'
  except:
    - master

# the 'pages' job will deploy and build your site to the 'public' path
pages:
  stage: deploy
  script:
    - honkit build . public # build to public path
    # 下記は、PlantUMLの画像がある日突然表示されなくなったので追加した
    - cp assets/images/uml/*.* public/assets/images/uml/
  artifacts:
    paths:
      - public
    expire_in: 1 day
  only:
    - master # this job will affect only the 'master' branch

利用しているプラグインについて

plugin	説明
gitbook-plugin-intopic-toc	Table of contents を出す
gitbook-plugin-collapsible-chapters	効いてない気がする
gitbook-plugin-hints	ヒント表示
gitbook-plugin-advanced-emoji	絵文字
gitbook-plugin-graph	グラフ書けるらしい(使ってない)
gitbook-plugin-edit-link	EDIT THIS PAGEのリンクが付けられる。Web IDEとつなぐと便利
gitbook-plugin-git-author	git から author を表示する
gitbook-plugin-hide-published-with	Published with Gitbook を消す
gitbook-plugin-changelog	git のログを表示する
gitbook-plugin-uml	PlantUMLを使う
gitbook-plugin-back-to-top-button	トップに戻るボタン追加
gitbook-plugin-copy-code-button	コードをコピーボタン追加(有効にしてなかった)
gitbook-plugin-custom-js-css	カスタムのJavaScript/CSSを追加できるようになる
gitbook-plugin-comments-footer	フッターにコメント欄追加(Gitlabでのログインと連動)
gitbook-plugin-insert-logo	ロゴを入れる
gitbook-plugin-search-pro-fixed	検索強化版
gitbook-plugin-recently-updated	最近の更新を表示(若干バグってる)
honkit-plugin-todo	TODOリストを作るもの

book.json

{
    "title": "Title",
    "plugins": [
        "uml",
        "-sharing",
        "intopic-toc",
        "collapsible-chapters",
        "hints",
        "advanced-emoji",
        "graph",
        "edit-link",
        "git-author",
        "hide-published-with",
        "todo",
        "back-to-top-button",
        "comments-footer",
        "custom-js-css",
        "changelog",
        "recently-updated",
        "insert-logo"
    ],
    "styles": {
         "website": "assets/website.css"
    },
    "pluginsConfig": {
        "custom-js-css": {
          "js": [
            "./assets/table-area.js"
          ]
        },
        "uml": {
            "charset": "UTF-8",
            "format": "png"
        },
        "edit-link": {
            "base": "https://GitlabのURL/-/ide/project/common/edocode-training/blob/master/-/",
            "label": "Edit This Page"
        },
        "git-author": {
            "position": "bottom",
            "modifyTpl": "Last modified by {user} {timeStamp}",
            "createTpl": "Created by {user} {timeStamp}",
            "timeStampFormat": "YYYY-MM-DD HH:mm:ss"
        },
        "comments-footer": {
            "type": "gitlab",
            "repo": "適当なリポジトリ",
            "copyright": "",
            "redirect": "https://Gitlab PagesのURL",
            "clientId": "トークン",
            "host": "https://GitlabのURL/"
        },
        "insert-logo": {
            "url": "ロゴへのパス/logo.png",
            "style": "background: none;"
        },
        "changelog": {
            "diffFilter" : "ADM",
            "dateFormat": "YYYY-MM-DD HH:mm:ss",
            "ignore": {
                "firstCommit": false,
                "files": [".gitlab-ci.yml", ".gitignore", ".bookignore", "book.json", "SUMMARY.md", "changelog.md"],
                "exts":  ["jpg", "png", "gif", "svg"],
                "commits": []
            }
        }
    }
}

gitbook-plugin-auto-scroll-table というのがうまくいかない

ので、gitbook-plugin-custom-js-css を使ってやっています。
これをしないと、横に長いテーブルが見切れて見えない。

以下、それ用のCSSとJavaScriptです。

assets/website.css

.page-inner {
  max-width: 80% !important; 
  width: 70% !important;
}
.table-area {
  overflow-x: auto;
}
.table-area table {
  width: 100% !important; 
  -webkit-overflow-scrolling: touch;
  white-space: nowrap !important;
  empty-cells: show;
}

assets/table-area.js

// copy from https://github.com/ideamean/gitbook-plugin-auto-scroll-table/blob/master/book/plugin.js
require(["gitbook", "jQuery"], function(gitbook, $) {
  gitbook.events.bind("page.change", function() {
    [].slice.call(document.querySelectorAll('table')).forEach(function(el){
        var wrapper = document.createElement('div');
        wrapper.className = 'table-area';
        el.parentNode.insertBefore(wrapper, el);
        el.parentNode.removeChild(el);
        wrapper.appendChild(el);
    });
  });
});

FSWiki to Markdown

FSWikiのフォーマットをMarkdownに変える必要があります。
どこかから拾ってきたものに手を入れたものです。下記においてます(一部バグってる気がします)。

バグってる点1: 箇条書きのところで、余計な改行が入ってしまうようです。下記を後から実行すれば直ると思います。

find -name '*.md' |grep -v '/node_modules' | xargs -i perl -mstrict -e 'my $file = $ARGV[0]; open my $nfh, ">", $file.".new"; open my $fh, "<", $file; my $aster = 0, my $code = 0; while(<$fh>){$_ eq "\n" and next if $aster; $code = /^\s*```/ ? ($code ? 0 : 1) : 0; $aster = (!$code and (/^\* / or ($aster and /^\s+\*/)) ) ? 1 : ((!$code and $aster) ? 2 : $aster);print $nfh "\n" and $aster = 0 if !$code and $aster == 2; print $nfh $_}; rename $file.".new" => $file' {}

終わり

以上で、なかなかいい感じなサイトができあがりました。

めでたし、めでたし...なのですが!

問題点

欠点がないわけではないです。

buildが遅い

600ファイル以上あるせいだとは思いますが、buildが30分程度かかります。ちょっと頑張ったら速くできるかなーとソースコードは追ってみたのですが、結構頑張らないと速くできそうにないので、一旦放置しています。

検索がいまいち

1ワードの検索なので、いまいちな感じは拭えません(特にファイル数が多いので)。
下記のプラグイン使ったらどうかなぁ、と思いつつ試せていません。

---

Wanoは積極的にエンジニア採用を行なっています！
まずはオンラインでVPoEとのカジュアル面談から。お好きな入り口からお気軽にお声がけください！
Wano Recruitページ　https://group.wano.co.jp/recruit/
QiitaJobs　https://jobs.qiita.com/employers/wano-inc/postings/1297
Wantedly　https://www.wantedly.com/companies/wano/projects
Findy　https://findy-code.io/companies/522

EDOCODEも積極的にエンジニア採用を行っています!
興味のある方は下記を参照ください。
Green https://www.green-japan.com/job/94118