Gitbook: установка, удаление, частые проблемы

GitHub ➡️ https://github.com/GitbookIO/gitbook-cli Текущая версия: 3.2.3.

• Установка, удаление и частые проблемы с GitBook.
• Конфигурация и оптимизация GitBook.
• Проблемы с генерацией pdf в GitBook: отображение китайского языка или искажённый текст.

Перед началом работы

— Глобальная установка gitbook:

npm install -g gitbook или yarn global add gitbook
npm install -g gitbook-cli

Команды для публикации (генерация документации): gitbook serve и для создания пакета: gitbook build.

Дополнительная настройка (необязательно)

1. Изменение сообщения об ошибке по умолчанию в теме GitBook

При использовании этой темы часто появляется сообщение об ошибке в консоли, причину которого не удаётся найти, и оно до сих пор не исправлено.

Тема.js:4 Uncaught TypeError: Cannot read property 'split' of undefined

Перейдите в каталог пользователя и откройте файл .gitbook/versions/3.2.3/node_modules/gitbook-plugin-theme-default/src/js/theme/navigation.js, найдите функцию getChapterHash и замените содержимое следующим образом:

    //var $link = $chapter.children('a'),
    //    hash = $link.attr('href').split('#')[1];

    //if (hash) hash = '#'+hash;
    //return (!!hash)? hash : '';
    var $link = $chapter.children('a'),
        hash,
        href,
        parts;

    if ($link.length) {
        href = $link.attr('href')
        if (href) {
            parts = href.split('#');
            if (parts.length>1) {
                hash = parts[1];
            }
        }
    }

    if (hash) hash = '#'+hash;
    return (!!hash)? hash : '';

Вернитесь в папку gitbook-plugin-theme-default и выполните команду npm install для повторной компиляции файла.

2. Изменение стиля по умолчанию для темы theme-default

Перейдите в каталог пользователя и откройте папку .gitbook/versions/3.2.3/node_modules/gitbook-plugin-theme-default/_layouts/website.

1. Измените favicon.ico и откройте файл layout.html, закомментируйте строки 9 и 10 с помощью <!-- -->.

2. Измените «Опубликовано с GitBook» и откройте файл summary.html. Найдите https://www.gitbook.com и измените его на свой блог и заголовок.

        <a href="https://zhousiwei.gitee.io" creator="https://github.com/JoeyBling" target="_blank" class="gitbook-link">
           Published with 试毅-思伟<!-- {{ "GITBOOK_LINK"|t }}{{t}} -->
        </a>

3. Изменение предупреждений в плагине prism

После каждого выполнения команды npm install появляются предупреждения:

# warn: "options" property is deprecated, use config.get(key) instead 
# warn: "options.generator" property is deprecated, use "output.name" instead

Откройте файл ./node_modules/gitbook-plugin-prism/index.js и измените строку 41 if (book.options && book.options.generator), заменив её следующим содержимым:

  if (/^2+\.\d+\.\d+$/.test(book.gitbook.version))

4. Настройка плагина tbfed-pagefooter

Откройте файл ./node_modules/gitbook-plugin-tbfed-pagefooter/index.js и замените его своим блогом и заголовком.

powered by 试毅-思伉

5. Изменение плагина статистики Baidu

Откройте файл ./node_modules/gitbook-plugin-baidu/book/plugin.js и замените его содержимое следующим образом:

require(["gitbook"], function (gitbook) {
    gitbook.events.bind("start", function (e, config) {
        config.baidu = config.baidu || {};
        var _hmt = _hmt || [];
        var hm = document.createElement("script");
        hm.src = "https://hm.baidu.com/hm.js?" + config.baidu.token;
        var s = document.getElementsByTagName("script")[0];
        s.parentNode.insertBefore(hm, s);
    });
});

6. Изменение плагина mygitalk для использования локальных ресурсов

Откройте файл ./node_modules/gitbook-plugin-mygitalk/index.js и замените его содержимое, а затем выполните команду для копирования локальных ресурсов: cp -rp ./gitalk/* ./node_modules/gitbook-plugin-mygitalk/assets/

        css: [
            // "https://unpkg.com/gitalk/dist/gitalk.css",
            "gitalk.css",
            "mygitalk.css"
        ],
        js: [
            // "https://unpkg.com/gitalk/dist/gitalk.min.js",
            "gitalk.min.js",
            "mygitalk.js"
        ]

Решение проблем

Поскольку gitbook официально отказался от поддержки gitbook-cli, большинство ошибок возникает из-за самостоятельного изменения исходного кода. Если возможно, может потребоваться разветвить gitbook-cli для его поддержки.

Официальная информация: https://github.com/GitbookIO/gitbook#%EF%B8%8F-deprecation-warning