Система документації

Маніфест
Налаштування Obsidian

Архітектура системи¶

Загальна ідея

flowchart LR
A(Вміст) --> B(Контроль версій)
C(Програмне забезпечення для редагування) --> A
A --> D(Зробити доступним онлайн)

Детальніше:

flowchart LR
A[Obsidian] <--> B{Файли}
B <--> C(Github Desktop)
C <--> D{Github}
B <--> E(MkDocs)
D --> F(Github Pages)
G(Тема: MkDocs-Material) --> E
H(MkDocs-Publisher) --> E
E --> D

Компоненти детально¶

1. Markdown¶

Переваги:

• Його легко вивчити та використовувати, що дозволяє мені зосередитися на вмісті.
• Він незалежний від платформи, тому я можу продовжувати роботу на будь-якому пристрої.
• Він ідеально підходить для контролю версій, що дозволяє мені відстежувати та керувати змінами.
• Він є перспективним і не є пропрієтарним, що дає мені впевненість у тому, що моя робота залишиться доступною в довгостроковій перспективі.

Markdown

2. Obsidian¶

• Я можу зберігати свої дані локально та редагувати їх офлайн, що дає мені гнучкість та контроль.
• Я можу легко пов'язувати файли між собою, що допомагає мені організовувати складну інформацію.
• Я можу позначати файли тегами та легко керувати ними, що надає мені додатковий вимір організації.
• Я можу візуалізувати свої дані, що допомагає мені розпізнавати закономірності та зв'язки.
• Я можу розширювати функціональність Obsidian за допомогою плагінів, що дозволяє мені адаптувати інструмент до моїх конкретних потреб.

3. Git та Github¶

Переваги:

• Контроль версій: Кожна зміна документується і може бути відстежена в будь-який час, що допомагає мені уникати помилок та зберігати загальний огляд.
• Співпраця: Кілька людей можуть одночасно працювати над документацією, що дає мені можливість інтегрувати відгуки та внески від інших.
• Резервне копіювання: Моя документація в безпеці та регулярно резервується, що дає мені впевненість у тому, що моя робота не буде втрачена.

4. Github Desktop¶

Переваги:

• Простота використання, що полегшує мені використання Git.
• Не потрібні знання командного рядка, що заощаджує мені час та зусилля.
• Спрощує мій робочий процес, дозволяючи мені зосередитися на створенні контенту.

5. MkDocs¶

Переваги:

• Просте створення вебсайту, що дозволяє мені швидко та легко публікувати свою документацію.
• Швидке оновлення, що дозволяє мені бачити зміни в режимі реального часу.
• Послідовний макет, що забезпечує професійний та єдиний вигляд моєї документації.
• Попередній перегляд офлайн, що дозволяє мені перевірити свою документацію перед публікацією.

6. Github Pages¶

Переваги:

• Безкоштовний хостинг, що дозволяє мені публікувати свою документацію без додаткових витрат.
• Проста публікація, що знімає з мене технічну реалізацію публікації.
• Надійність, що дає мені впевненість у тому, що моя документація завжди доступна.

7. MkDocs-Material¶

Переваги:

• Сучасний дизайн, що робить мою документацію професійною та актуальною.
• Налаштовуваність, що дозволяє мені адаптувати макет до моїх конкретних потреб.
• Зручність для користувача, що полегшує мені використання документації.

8. MkDocs-Publisher¶

Переваги:

• Спрощена інтеграція з Obsidian: Автоматичне налаштування синтаксису Markdown Obsidian (Callouts, Wikilinks тощо).
• Розширені метадані: Інтеграція тегів та категорій з Obsidian Frontmatter.

Робочий процес¶

1. Я створюю та редагую файли Markdown за допомогою текстового редактора (необов'язково Obsidian).
2. Я зберігаю файли Markdown локально.
3. Я передаю свої зміни до репозиторію Git за допомогою Github Desktop.
4. Я автоматично генерую вебсайт за допомогою MkDocs.
5. Я публікую вебсайт за допомогою Github Pages.

Файлова система¶

/docs/     (Тут знаходяться мої файли Markdown)
/site/     (Тут генерується вебсайт)
license    (Інформація про ліцензію)
mkdocs.yml (Файл конфігурації для MkDocs)
readme.md  (Файл з описом репозиторію)

Альтернативи для створення контенту¶

1. Wordpress: Вміст може бути створений у Wordpress як сторінка.
2. Текстовий файл, файл Word: Вміст може бути створений як текстовий файл, файл Word (або в інших типових форматах).

У цих випадках я можу потім інтегрувати вміст у систему.