Наш побочный проект Threadbase позволяет любому создать собственное сообщество в стиле Reddit всего за несколько кликов - кодирование не требуется. Внешний интерфейс - это React, а Rails поддерживает нашу серверную часть, но наша цель состоит в том, чтобы владельцам нашего сообщества не нужно было ничего знать об этом. Фактически, если мы делаем свою работу правильно, наши пользователи могут создавать успешные сообщества, подобные Hacker News, без написания кода.
Однако после нескольких телефонных разговоров с нашими пользователями мы поняли, что должны проявлять большую активность в предоставлении документации о Threadbase и о том, как получить от нее максимальную отдачу.
Сначала мы думали о создании новой модели в Rails для документации, но это быстро превратилось в массу вопросов вроде «Нужно ли нам настраивать права администратора на интерфейсе для ведения блога?» Нужно ли нам создавать кучу новых представлений для интерфейса блога? Будем ли мы рендерить блог с помощью React или Rails? Как мы работаем с маршрутизацией? »
То, что должно было быть простой идеей - давайте создадим документацию, чтобы помочь нашим пользователям - стало совершенно новым продуктом, и нам пришлось сделать шаг назад и спросить себя: «Можем ли мы сделать MVP нашей документации, в которой есть все, что нам нужно для помочь нашим пользователям, но резко сократить объем кода, который нам нужно написать? »
Входит Джекилл.
После некоторого обсуждения того, что мы могли бы использовать, мой соучредитель поднял Jekyll, простой генератор статических сайтов. Он использует его для своего личного веб-сайта и считает, что мы могли бы использовать его для нашей документации, а не создавать дополнительное приложение CRUD внутри Threadbase для обработки документации.
Посмотрев на него, Джекилл начал понимать смысл. Вот почему:
- Jekyll берет текст, написанный в разметке, и превращает его в статический веб-сайт.
- Если вы хотите создать больше страниц или категорий, вы можете, указав эту информацию в файле конфигурации и на странице, которую вы создали.
- Скорее всего, нам не нужно будет вносить изменения в завершенные статьи в наших документах, но если мы это сделаем, мы можем просто обновить наши файлы разметки, Jekyll автоматически обновит страницы для нас, а затем мы можем развернуть код в производственной среде для внесения обновлений. .
Это означает, что новое развертывание требуется каждый раз, когда мы хотим внести изменения в документацию, но для MVP Jekyll идеально подходит для того, что нам нужно, и значительно сокращает объем кода, который нам нужно написать.
Создание блога документации Jekyll
Чтобы начать работу с Jekyll, убедитесь, что у вас установлен Jekyll, используя:
$ gem install bundler jekyl
Отсюда мы обычно запускаем стандартную команду для создания нового сайта (jekyll new documentation-site), но вместо того, чтобы начинать с чистого листа, мы нашли идеальную тему для нашего сайта документации под названием jekyll-docs-template:
Итак, мы клонировали это репо вот так:
git clone https://github.com/bruth/jekyll-docs-template/ docs
Оттуда перейдите в свое новое репо и извлеките необходимые зависимости:
cd docs bundle install
И как только пакет будет завершен, вы воспользуетесь следующей командой, чтобы запустить свой сайт документации:
bundle exec jekyll serve
Ваша среда разработки для вашего нового сайта документации теперь запущена и работает на localhost:4000!
Настройка блога документации Jekyll
После клонирования репо перейдите к файлу _config.yml, и вы увидите, что репо уже содержит массив с именем Sections. Здесь вы сможете настроить различные разделы вашей документации.
Ниже приведены разделы, которые у нас есть для Документации по Threadbase:
# Default categories (in order) to appear in the navigation sections: [ [‘doc’, ‘Documentation’], [‘start’, ‘Getting Started’], [‘cus’, ‘Customizing’], [‘man’, ‘Community Management’], [‘theme’, ‘Themes’], [‘post’, ‘Posts’], ]
Теперь, если вы хотите создать страницу для одного из своих разделов, вы можете либо создать новый файл в каталоге _posts, либо использовать удобный сценарий ниже:
ruby bin/jekyll-page "<your page title>" <your section>
Таким образом, настоящая команда может выглядеть примерно так:
ruby bin/jekyll-page "Overview" cus
Будет создано сообщение с именем Overview, имеющее категорию cus для нашей категории настройки, и оно будет выглядеть следующим образом:
--- layout: page title: "Overview" category: cus date: 2019-02-05 17:23:29 ---
Отсюда вы можете начать вводить текст под ---, и Jekyll сгенерирует для вас соответствующий HTML.
Наш последний пост для обзора Threadbase выглядит примерно так:
--- layout: page title: "Overview" category: cus date: 2019-02-05 17:23:29 order: 1 --- Threadbase's most valuable feature is that you can customize your community without writing any code. We've made everything easily adjustable with text and check boxes, and everything can be changed in your Dashboard. To access your Dashboard, you'll need to visit https://threadbase.io and log in to your community owner account. Once you do and you have created at least 1 community, you'll be dropped into your Dashboard, which should look like the below: {: .hero-image } To customize your community, you'll use the options on the left-hand navigation. {: .hero-image } --- Use the below options to learn more about specific types of customization options: - [General Settings](..{% post_url 2018-11-28-general-settings %}) - [Registration Settings](..{% post_url 2018-11-28-registration-settings %}) - [Design](..{% post_url 2018-11-28-design %}) - [Social](..{% post_url 2018-11-28-social %})
Прежде чем мы завершим и сгенерируем наш статический сайт, мы хотим сделать две важные вещи: 1) добавить наш идентификатор Google Analytics, чтобы мы могли отслеживать посещения, и 2) добавить baseurl для нашего сайта документации для SEO-оптимизации (подробнее в следующем разделе ).
Чтобы внести эти два изменения, вернитесь в _config.yml и найдите две строки ниже:
# if you use google analytics, add your tracking id here google_analytics_id: 'UA-1234567890–1' ... # path (e.g. on GitHub pages) leave off the trailing slash, e.g. /my-project baseurl: '/docs'
Введите наш идентификатор Google Analytics (он должен выглядеть как UA-1234567890–1) внутри '', и ваше отслеживание будет готово.
И для baseurl мы используем /docs для нашей подпапки, так что это то, что мы туда поместили.
Теперь, когда они устранены, мы можем сгенерировать наш статический сайт, поместить наши документы в наше приложение Rails и закончить!
Создание статического сайта и оптимизация документации для SEO внутри Rails
Вы можете быстро сгенерировать свой сайт с помощью следующей команды:
jekyll build
В вашем каталоге теперь будет новая папка с именем _site, которая содержит все файлы, которые вам понадобятся для ваших документов, без написания кода!
Но, как упоминалось выше, одной из важных вещей, которые я хотел сделать для наших документов, было сделать их оптимизированными для SEO, поместив их в подпапку нашего основного домена (в нашем случае https://threadbase.io), а не чем субдомен, потому что эти документы относятся к нашему основному домену. И хотя есть много споров о том, действительно ли это имеет значение, я буду использовать эту цитату как лучшее резюме:
Основываясь на своем исследовании, Moz пришел к выводу, что вложенные папки лучше всего подходят для SEO из-за различных показателей, возвращаемых различными поисковыми системами. Он поддерживает использование поддомена только для иностранных языковых вариантов основного веб-сайта, если это необходимо. (Источник: Impactbnd)
Итак, поскольку мы знаем, что хотим поместить наши документы в подпапку нашего основного приложения, вопрос в том, как это сделать?
И ответ: это довольно просто, потому что мы уже проделали большую работу!
Ранее мы добавили baseurl для наших документов в _config.yml, и поэтому все, что нам нужно сделать, это взять сгенерированную папку _sitemap и все ее содержимое, вставить ее в наше приложение Rails в папку public и переименовать папку docs.
Если все сделано правильно, в вашем приложении Rails будет общая папка, которая выглядит примерно так:
Поздравляю! После того, как ваше приложение Rails будет развернуто в производственной среде, теперь у вас будут:
- Проект документации, который легко обновляется, на платформе Jekyll.
- Новый раздел документации на вашем сайте, чтобы вы могли подключать своих пользователей и заранее отвечать на их вопросы. Он будет доступен по адресу
yourdomains.com/docs/. Для Threadbase это означает, что наши документы размещены здесь: https://threadbase.io/docs - Этот новый раздел документации будет находиться в выбранной вами подпапке, чтобы воспользоваться преимуществами SEO, такими как наша документация Threadbase.
Я надеюсь, что это позволит другим разработчикам быстрее получить свою документацию!
—
Крис является соучредителем Threadbase: платформы, которая позволяет людям, не являющимся разработчиками, создавать свои собственные сообщества в стиле Reddit всего за несколько кликов.
До Threadbase Крис работал в маркетинге для стартапов, включая Quidsi и ComiXology (оба были приобретены Amazon) и Bonobos (приобретены Walmart).
