База знаний

Больше всего вы просили меня рассказать про базу знаний.

И самый смешной комментарий был не про базу знаний, он был в ролике про то, почему я люблю линукс. Там человек сказал, что самый большой недостаток линукса в том, что все слишком хорошо работает и ты забываешь как ты это настроил. И я сразу подумал, что это просто лучший комментарий для ролика про базу знаний.

Что такое база знаний и зачем она

Фактически, база знаний как раз и нужна для того чтобы не было проблем как у человека из комментария.

Ты что-то делаешь, а через время забываешь решение.

Так же база знаний крайне важна в компаниях. В любой компании есть текучка. И когда приходит новый человек он не отвлекает всех людей вокруг себя, а просто читает базу знаний. Это экономит большое количество времени.

Столкнулся с проблемой - описал ее.

Чтобы и ты и люди после тебя не наступали на те же самые грабли.

Что важно в базе знаний?

Тут уж каждый решает сам что ему важно. Если вам удобно хранить все в обычном текстовом файлике на рабочем столе, то на здоровье. Но такой вариант работает, только если у вас слишком мало знаний.

Я перечислю вещи, которые важны мне.

• Удобное форматирование. Мне должно быть удобно читать все в своей базе. Поэтому там должно быть ясное форматирование. Поэтому в любом случае я буду использовать маркдаун.
• Гибкость. Я не хочу привязываться к какой-то системе. Поэтому я не использую какие-нибудь сервисы вроде Evernote или Notion. Завтра эти сервисы могут поменять политику или закрыться. А я не хочу ничего менять в своем wofkflow. Поэтому я просто создаю .md файлы локально, а дальше уже выбираю инструмент, который их отображает.
• Красивое отображение md файлов. Отображать тоже надо адекватно. Так, например, mardown выглядит отлично на гитлабе и ужасно в каком-нибудь Raneto.
• Роли. Если пользователь не один, и вы, например, используете базу в компании, то для вас будут важны роли.
• Логинка. Я не хочу выности базу в паблик, поэтому инструменты позволяющие задать пароль мне нравятся больше.
• Редактирование. Совсем круто если ты можешь редактировать свою базу прям там где просматриваешь, но редко такое возможно.

Markdown

Некоторые люди ведут свою базу просто в текстовых файлах. Другие в каких-нибудь гугл документах.

И все эти варианты они ужасны.

В текстовых файлах нет форматирования. А какие-нибудь гугл-доки вообще не предназначены для документации. У них даже вид листика. Это значит, что они нужны для бумажных документов. Которые ты собственно будешь распечатывать. Иначе я не понимаю зачем там форма листка.

Можно так же использовать различные сервисы NOTION, Confluence.

Это отличные решения. У них только два минуса:

• Платные.
• Отсутствие гибкости. Какой дали тебе интерфейс, такой ты используешь. Ты не можешь ничего поменять.

Поэтому, мне лично нравится вариант, который уже сто лет используют программисты. Он используется как стандарт для описания проектов. Например, вы можете зайти практически на любой проект в гитхабе и увидеть там файл README.md он же отображается когда вы смотрите описание проекта.

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

Можете посмотреть тут как это работает - https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

И мне этот вариант нравится тем, что ты никак не ограничен инструментами. Ты можешь редактировать свою базу знаний в любом удобном лично для тебя редакторе. Я, например, редактирую в редакторах Vim или в Typora.

Мне оба варианта нравятся.

Для отображения базы знаний на локальной машине в принципе ничего не нужно.

Но при этом надо понимать, что во-первых, мы с вами можем захотеть синхронизировать нашу базу знаний между нашими устройствами. Ну, например, мы хотим что-то посмотреть с планшета.

А во-вторых мы хотим чтобы эта база знаний была доступна везде. Даже если я не за компьютером и не дома. А где-нибудь далеко и с телефоном.

VIM + MARKDOWN

Мне больше всего, все-таки нравится использовать Vim при написании чего-то в базу знаний.

Во-первых это просмотрщик. Как только вы открываете какой-то *.md файл у вас разу же открывается рядом браузер, в котором вы видите как это все будет выглядеть.

Во-вторых таблицы. Их тут очень легко создавать и редактировать из-за различных плагинов. Во-первых довольно легко создать таблицу снипетом. (Например. tb5x5 создаст таблицу с 5 колонками и 5 ячейками). Так же есть удобный плагин, который автоматически расширяет колонки если в какой-то колонке появляется значение с большой шириной. Это трудно объяснить, но легко показать, так что смотрите гифку ниже.

Так же довольно легко обрамлять код делая его жирным или курсивом. Так же легко обрамлять блоки кода. Быстро добавлять ссылки или картинки.

Но так же мне нравится использовать и другую программу, которая называется Typora. Я использую ее на маке. Она отлично выглядит, имеет очень минималистичный интерфейс. И показывает только одно окно, когда пишешь md, то он сразу же сворачивается и разворачивается только та область, на которой сейчас находится курсор. Но если надо развернуть весь md, то можно просто нажать cmd+/

Выглядит там все вот так:

Синхронизация

Естественно нам нужно синхронизировать наши записи между нашими девайсами. Поэтому будем использовать git.

Я использую свой GitLab сервер. Я уже говорил как его можно развернуть.

Можете посмотреть видео тут.

Отображение

А для того чтобы отображать данные, есть различный софт. Но сразу хочу сказать, что он весь не идеальный. У каждого есть свои плюсы и минусы. Я вот так или иначе использую сейчас пять вариантов. По крайней мере слежу за развитием каждого из этих инструментов.

Кстати, если вдруг вы знаете инструмент лучше, то пожалуйста расскажите про него. Я думаю вы поняли мои критерии. Можете мне написать на имейл или в комменте, как вам удобнее.

• Raneto
• MarkServ
• GitLab
• wiki.js
• Gitbook

Все, что делают эти штуковины так это берут ваши статичные файлы и показывают вам их в интернете.

Raneto

Raneto - очень легкая штука, просто отображает md файлы, но при этом имеет какой-то прям уродский дизайн. Самый большой недостаток в том, что там нет фолдинга. У меня прям большое количество документов и из-за этого сайдбар у рането просто бесконечный. Выглядит ужасно. И еще цветовая гамма, ну прям тоже так себе.

Отображение кода прям уродское. Не понятно кто придумал этот желтый стиль.

И кстати еще одна проблема в том, что там не отображаются картинки. Когда во всех остальных решениях все показывается отлично.

Короче говоря, рането странный. Скорее всего я его не рекомендую.

GitLab

Да, хоть он совсем для этого не предназначен, но он мне очень нравится. И его вполне можно использовать как базу знаний.

У него самый нормальный дизайн. Самый приятный. Именно того как отображается текст. Цветовая гамма, отступы, выделения. Прям очень здорово.

Но, конечно, не удобно постоянно логиниться в гитлаб, когда нужно что-то посмотреть. Ведь там постоянно надо вводить длинный пароль и двухфакторку. Поэтому это не удобно.

Wiki.js

Wiki.js - эта штука уже гораздо мощнее. В ней есть роли. И если у вас компания, то для вас это большое преимущество. Вы можете сделать базу знаний для сейлзов отдельно, для менеджеров отдельно, для программистов отдельно, для дизайнеров отдельно. И у каждого будет своя область видимости. Для каждого раздела можно назначить кого-то кто будет только просматривать и кого-то кто сможет делать правки.

И да, правки можно делать прям на сайте. То есть если все остальные инструменты в списке только отображают md файлы, то wikijs работает с гитом туда-сюда.

То есть вы прям там можете нажать на кнопку “New page” и прям там создать новую статью, отредактировать ее, и она автоматически закачается в GIT.

Это круто.

Но у нее большой минус. Во-первых она не умеет искать по тексту. Ищет только по названию файла. И это прям странно. Даже Raneto такое умеет. Опять же, когда у вас прям большое количество файлов, то вам гораздо проще вбить в поиск, чем искать вручную. Даже в GitLab есть поиск по тексту.

Ну и не очень большой минус это дизайн, опять же. Он какой-то такой. Из 2005 года. Уродство.

И еще, я не сразу вижу все файлы, когда я захожу туда. Я вижу пустую страницу, а чтобы увидеть все статьи мне надо нажать “All Pages”. Это странно. Там автоматически не подгружаются картинки. Я не знаю почему, возможно, это я что-то не так настроил.

Вложенность тоже отображается довольно странно. Если я зайду в папку, то увижу там не только название файлов внутри директории, но там рядом еще будет название родительской папки. И название получается довольно длинным. Не понятно для чего это вообще так сделано. Очень странно.

Но опять же, минусы мелкие. Особенно по сравнению с плюсами. Это редактирование прям на сайте, и синхронизация с гитом. Ну и разделение прав. Такое мало где есть.

MarkServ

Эта штука похожа на Raneto. Она тоже просто отображает статичные файлы.

Главная страница, конечно, выглядит не очень.

Тут нет поиска, но зато тут отличное отображение самих файлов. Такое же как в гитхабе.

Gitbook

И вот мы дошли до моего любимого инструмента.

На данный момент мне он нравится больше всех остальных. Он есть просто на гитхабе как сервис, но так же вы можете развернуть его у себя на сервере.

Мне, конечно, второй вариант нравится куда больше.

Тут отличное отображение файлов. И вообще сам дизайн у гитбука отличный.

Мне так же очень нравится что тут есть классный фолдинг. Работает просто отлично.

Так же тут есть одна особенность, в отличие от всех остальных инструментов, которые были выше. Тут нет автоматической генерации. Если в предыдущие решения вы просто скидывали маркдаун файлы и все происходило автоматом, то тут есть еще файлик, который называется SUMMARY.md и в нем вы описываете дерево файлов, которое будет отображаться слева.

В этом подходе есть как плюсы так и минусы. Плюсы в том, что вы сами формируете вот эту ветку. А минусы в том, что при добавлении файла надо менять файл SUMMARY.md

Но как я уже сказал, мне этот подход скорее нравится, чем не нравится.

Кстати, файл SUMMARY.md в самом начале можно просто сгенерировать, чтобы не писать все вручную.

В общем-то единственный минус Gitbook, который есть для меня это отсутствие логинки. Приходится как-то городить ее самостоятельно.

УСТАНОВКА

Теперь давайте покажу как это все можно установить.

Как устанавливать GitLab я уже показывал тут.

Наверное не буду показывать как установить Raneto и MarkServ, так как там это делается одной командой.

Давайте покажу как устанавливать wiki.js и gitbook

Wiki.js

Довольно большое количество мануалов по установке wiki.js являются нерабочими. Этот работает.

Создаем дроплет в DigitalOcean, самый дешевый с убунтой. Если вы вдруг забыли, но я напоминаю вам, что можно воспользоваться моей рефералкой

Устанавливаем таймзону:

sudo dpkg-reconfigure tzdata

Обновляем убунту:

sudo apt update && sudo apt upgrade -y

Устанавливаем пакеты:

sudo apt install -y curl wget vim git unzip socat bash-completion apt-transport-https build-essential

Устанавливаем Node.js:

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt install -y nodejs 

Проверяем версии:

node -v && npm -v
# v10.15.1
# 6.4.1

Обновим npm

sudo npm install -g npm@latest

Проверим версию

npm -v# 6.8.0

Устанавливаем монгу:

sudo apt install -y mongodb

Проверяем версию:

mongo --version | head -n 1 && mongod --version | head -n 1
# MongoDB shell version v3.6.3
# db version v3.6.3

Стартуем монгу:

sudo systemctl start mongodb.service
sudo systemctl enable mongodb.service

Получаем сертификат:

Скачиваемacme.sh:

sudo su - root
git clone https://github.com/Neilpang/acme.sh.git
cd acme.sh 
./acme.sh --install --accountemail your_email@example.com
source ~/.bashrc
cd ~

Проверяем версию:

acme.sh --version# v2.8.1

Просим сертификат для нашего домена. Замените example.com на ваш домен.

# RSA 2048
acme.sh --issue --standalone -d example.com --keylength 2048
# ECDSA
acme.sh --issue --standalone -d example.com --keylength ec-256

Проверяем:

acme.sh --list

Перемещаем сертификаты:

mkdir -p /etc/letsencrypt/example.com
mkdir -p /etc/letsencrypt/example.com_ecc

Устанавливаем:

# RSA
acme.sh --install-cert -d example.com \ 
        --cert-file /etc/letsencrypt/example.com/cert.pem \
        --key-file /etc/letsencrypt/example.com/private.key \
        --fullchain-file /etc/letsencrypt/example.com/fullchain.pem \
        --reloadcmd "sudo systemctl reload nginx.service"

# ECC/ECDSA
acme.sh --install-cert -d example.com --ecc \
        --cert-file /etc/letsencrypt/example.com_ecc/cert.pem \
        --key-file /etc/letsencrypt/example.com_ecc/private.key \
        --fullchain-file /etc/letsencrypt/example.com_ecc/fullchain.pem \
        --reloadcmd "sudo systemctl reload nginx.service"
exit

Устанавливаем Nginx:

wget https://nginx.org/keys/nginx_signing.key
sudo apt-key add nginx_signing.key
rm nginx_signing.key
sudo -s
printf "deb https://nginx.org/packages/mainline/ubuntu/ $(lsb_release -sc) nginx\ndeb-src https://nginx.org/packages/mainline/ubuntu/ $(lsb_release -sc) nginx\n" >> /etc/apt/sources.list.d/nginx_mainline.list
exit
sudo apt update
sudo apt install -y nginx

Проверяем версию:

sudo nginx -v
# nginx version: nginx/1.15.8

Стартуем NGINX:

sudo systemctl enable nginx.service
sudo systemctl start nginx.service

Меняем конфиг:

sudo vim /etc/nginx/conf.d/wiki.js.conf
server {
    
    listen [::]:443 ssl http2;
    listen 443 ssl http2;
    listen [::]:80;
    listen 80;
    
    server_name example.com;

    charset utf-8;
    client_max_body_size 50M;

    ssl_certificate /etc/letsencrypt/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/example.com/private.key;
    ssl_certificate /etc/letsencrypt/example.com_ecc/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/example.com_ecc/private.key;
    
    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_next_upstream error timeout http_502 http_503 http_504;
    }
    
}

Тут измените строку “server name” и строки “ssl_sertificate”

Тестируем конфиг:

sudo nginx -t

Перегружаем NGINX:

sudo systemctl reload nginx.service

Настраиваем wiki.js. Создаем папку:

sudo mkdir -p /var/www/wiki.js
cd /var/www/wiki.js

Создаем пользователя:

sudo useradd -d /var/www/wiki.js wikijs

Меняем права:

sudo chown -R wikijs:wikijs /var/www/wiki.js

Запускаем скрипт из под нового пользователя:

cd /var/www/wiki.jssudo su wikijs
curl -sSo- https://wiki.js.org/install.sh | bash

Проверяем версию:

node wiki --version# 1.0.117

Когда все установилось начинаем конфигурацию

node wiki configure

И теперь переходим в браузер. Там все стандартно. Нужно просто указать свой домен (вместе с https, но без последнего слеша. Пример: https://bfg.dev). Так же нужно указать порт 3000.

Установка GitBook

Точно так же, создаем дроплет в DigitalOcean. Если вы вдруг забыли, но я напоминаю вам, что можно воспользоваться моей рефералкой

Устанавливаем таймзону:

sudo dpkg-reconfigure tzdata

Обновляем убунту:

sudo apt update && sudo apt upgrade -y

Устанавливаем пакеты:

sudo apt install -y curl wget vim git unzip socat bash-completion apt-transport-https build-essential

Устанавливаем Node.js:

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt install -y nodejs 

Проверяем версии:

node -v && npm -v
# v10.15.1
# 6.4.1

Обновим npm

sudo npm install -g npm@latest

Проверим версию

npm -v# 6.8.0

Далее создаем директорию

sudo mkdir /var/www/gitbook
cd /var/www/gitbook

Сразу же сюда клонируем нашу репу из гитлаба, моя будет создана в папке “knowledge_base”.

Теперь установим гитбук глобально

npm install gitbook-cli -g

И установим его в текущую папку

gitbook init

Теперь в текущей папке у нас будет создан гитбук и мы его даже сможем запустить. Но пока не будем этого делать, нам нужно его немного настроить.

Создаем файл book.json

vim book.json

Со следующим содержимым

{
        "root": "./docs",
        "title": "dpkb",
        "author": "devpew",
        "description": "just my knowledge",
        "plugins": [
                "folding-chapters-2",
                "theme-code",
                "-sharing"
        ],
        "pluginsConfig": {
                "theme-default": {
                        "showLevel": false
                }
        }
}

Там мы указали некоторые модули, которые мы будем использовать. Теперь их нужно установить командой:

gitbook install

Переместим файлы README.md и SUMMARY.md

mv README.md SUMMARY.md /knowledge_base

Практически все готово. Теперь если мы запустим нашу базу знаний то там будет только один файл. И это потому, что до запуска нам нужно сгенерировать файл SUMMARY. Мы, конечно, можем это делать вручную. Но когда у нас 230 файлов это делать тяжеловато.

На помощь нам приходит плагин

npm install -g gitbook-summary

Теперь запускаем его

book sm g

Все. Файл сгенерирован. Теперь можем запускать нашу базу.

gitbook serve