Инструкции по редактированию веб-сайта Kovri

Тема в разделе "Мануалы", создана пользователем MoneroRus, 13 июн 2018.

  1. MoneroRus

    Команда форума Модератор Редактор

    Регистрация:
    30 ноя 2017
    Сообщения:
    194
    Симпатии:
    40
    Содержание

    1. Введение
    2. Инструкции

    1. Изменить или добавить элементы дизайна (Jekyll)
    1. Jekyll
    2. Необходимые плагины
    3. GitHub
    2. Изменить или добавить страницы(Markdown)
    1. О GitHub и Markdown
    2. .html: форматирование и не только
    3. Пишем свою страницу
    4. Поддержка нескольких языков
    5. Навигация (и еще немного про поддержку нескольких языков)
    3. Для перевода
    1. Скопируйте (fork) этот код!
    2. Для начала
    3. Переведи!
    4. Наведение порядков
    3. Выбираем макет
    4. Вопросы & Контакты


    1. Введение

    Здорова всем, я rehrar. Парень, ответственный за создание пользовательского фреймворка и дизайна, который используется на веб-сайтах getmonero.org и getkovri.org. Если вы это читаете, то, скорее всего, хотите узнать, как редактировать страницы или добавлять содержимое, или как его удалять. Во-первых, позвольте сказать, огромное спасибо! Monero Project создан и запущен сообществом, и вы помогаете ему стать лучше.

    Есть несколько отличий между сайтами Kovri и Monero, поэтому я просто хочу подчеркнуть, вы читаете инструкции для сайта Kovri.

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

    По любым вопросам, или если вам необходимо с нами связаться, можете найти нас на IRC канале #kovri-dev. Мы сделаем все возможное, чтобы вам помочь.

    2. Инструкции

    Итак, внимание, пожалуйста...

    2.1 Изменить или добавить элементы дизайна (Jekyll)

    Данный раздел для тех, кто хочет изменить любой из следующих элементов на сайте:
    • Заголовок
    • Навигацию
    • Подвал (Footer)
    • Макеты страниц
    Навигация автоматически обновляется с добавлением страниц, при условии соблюдения инструкций, поэтому если вы просто добавляете новую страницу, можете не переживать об этом. Если вы не собираетесь делать ничего из выше перечисленного, переходите к разделу 2.2.

    2.1.1 Jekyll

    Все еще тут? Отлично, Тогда переходим к делу. Сайт Kovri сделан с использованием простого генератора статических веб-сайтов, называемого Jekyll. Это значит, что если вам требуется внести значительные изменения в код всего сайта, вам необходимо установить Jekyll на свой компьютер. Jekyll работает на Ruby, поэтому он вам тоже потребуется. Я исхожу из предположения, что вы уже ознакомились с документацией по Jekyll, поэтому не буду подробно на нем останавливаться.

    2.1.2 Необходимые плагины

    Сайт Kovri использует следующие плагины:

    ПОЖАЛУЙСТА, ПРОЧТИТЕ ВСЮ ДОКУМЕНТАЦИЮ, СВЯЗАННУЮ С КАЖДЫМ ПЛАГИНОМ

    Если в будущем на сайт будут добавлены какие-либо другие плагины, этот документ будет дополнен названиями и ссылками.

    2.1.3 GitHub

    Во-вторых, вам потребуется скопировать(fork) сайт Kovri с GitHub для работы с вашим собственным репозиторием. И да, это тоже означает, что вы должны знать как работает GitHub и система контроля версий. Не переживайте, если у вас есть вопросы, сообщество Kovri действительно с радостью поможет.

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

    2.2 Изменить или добавить страницы(Markdown)

    Если все, что вы хотите, это добавить или изменить страницы на сайте, вам повезло! Вам не потребуется знать много вещей из раздела 2.1. Вот несколько вещей, которые вам все равно необходимо сделать, поэтому начнем.

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

    2.2.1 О GitHub и Markdown

    Погнали дальше, копируем(fork) сайт Kovri или качаем файлы с GitHub. Не переживайте, вам не потребуется Jekyll или еще что-то на вашем компьютере. У вас должна быть возможность редактировать файлы через веб интерфейс GitHub.

    Прежде всего, вам нужно знать, как использовать Markdown. Это по большей части промежуточный язык, который позволяет людям без знания HTML просто написать, и это будет преобразовано в HTML для вас. Можете посмотреть отличную шпаргалку с примерами здесь. Если вам требуется больше помощи, Google и YouTube отличные ресурсы для этого.

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


    2.2.2 .html: форматирование и не только

    Отлично, давайте сделаем страницу. Первым шагом будет переход в папку 'doc' в корне сайта. Здесь вы увидите несколько страниц с окончанием .html. Щелкните 'Создать Новый Файл(Create New File)' и введите имя файла с .html в конце. Мы будем использовать kovri-example.html для примера.

    Ок, теперь сюда мы вставляем весь наш клевый контент, верно? Верно, но не совсем. Jekyll требует, чтобы в начале файла находился специальный титульник (вступительная часть, front matter), который выглядит примерно так:
    Код:
    ---
    layout: default
    title: titles.faq
    permalink: /FAQ
    ---
    
    Это титульный лист для faq.html. Давайте его разберем.
    • layout: Каждой странице нужен макет(layout). Для большинства целей хорошо подойдет 'default'. Это просто одиночный информационный блок в полную ширину, как тот, что можно увидеть на стартовой странице Kovri. Смотри раздел '3. Выбираем макет' для дополнительной информации.
    • title: Это заголовок вашей страницы. На самом деле вы указываете здесь не сам заголовок, а что-то, что укажет на ваш заголовок в мульти-переводе. Вам надо указать слово 'titles', затем точка, после которой следует уникальное слово, описывающее вашу страницу. В примере выше, это выглядит так titles.faq. Для нашего примера, kovri-example.html, можем указать titles.example. Когда все пошло не так, название страницы отлично выручает.
    • permalink: Так будет доступна ваша страница. Например, вы можете получить доступ к странице the Kovri FAQ, набрав https://getkovri.org/faq. /faq в конце - это и есть постоянная ссылка(permalink). Выберите уникальное слово для вашей страницы и укажите '/' перед ним. Для нашего примера мы можем выбрать что-то типа /kovri-example.
    Ok, когда мы все это уладили, давайте перейдем к остальной части нашей страницы. Посмотрим, что осталось на странице FAQ:
    Код:
    {% tf faq.md %}
    
    Погоди, это все? Да, это все. Не верите? Щелкните на faq.html в папке doc и убедитесь самостоятельно. Титульник и эта одна строка составляют весь файл. О чем она говорит? Что ж давайте рассмотрим ее еще раз:
    • {% %}: эти скобки в начале и в конце просто говорят о том, что код надо выполнить. Это очень важно, не забудьте их.
    • tf: tf означает перевод файла(translate file). Это говорит найти подходящий перевод вашей страницы и поместить его сюда, в зависимости от того, какой язык выбрал пользователь сайта.
    • faq.md: А вот тут вам надо что-то сделать. Надо снова выбрать уникальное имя и поместить его сюда с окончанием .md. Запомните это имя. Оно нам понадобиться позже. Для нашего примера мы можем написать: kovriexample.md.
    Примечание:
    Если вам хочется использовать одно и то же уникальное имя для всех описанных переменных (title, permalink, и имя md файла), это нормально. Оно просто должно быть уникально для вашей страницы в рамках всего сайта.


    2.2.3 Пишем свою страницу

    Ожидали большего? Не переживайте, мы еще не закончили. Выйдите из папки doc и найдите папку _il8n. В зависимости от числа текущих языков на сайте, тут будет соответствующее количество папок и файлов. К сожалению, здесь есть некоторые проблемы. Не сложные, просто отнимающие немного времени. Давайте начнем с посещения папки en (что значит English). В ней вы увидите несколько файлов с окончанием .md. Помните уникальное имя, которое вы придумали ранее для своего файла .md? Сейчас мы будем его использовать. Щелкните Создать Новый Файл(Create New File) и назовите его В ТОЧНОСТИ с тем именем, которое вы выбрали ранее. В нашем примере: kovriexample.md.

    Тут вы можете применить ваши новоприобретенные навыки в markdown для создания своей страницы. Не создавайте титульный лист для этой страницы. Это все испортит. Просто пишите свой контент. Я подожду.

    ...

    ...

    Все готово? Великолепно! Сохранитесь, чтобы не потерять, то что сделали. Это должно перенаправить вас на страницу GitHub, где будет показано, как выглядит твой markdown. Если требуется что-то изменить, сделайте это сейчас. Поверьте мне. Трижды все проверьте, чтобы убедиться, что все так, как вы хотели. Если не проверите, не говорите, что я вас не предупреждал.

    2.2.4 Поддержка нескольких языков
    Теперь нажмите кнопку Raw в верхнем правом углу вашей работы и нажмем CTRL + A, затем CTRL + C. На данный момент ваша страница скопирована в буфер обмена. Нажмите на кнопку назад (браузера) и переходите к папке следующего языка. Допустим, это es для испанского. Нажмите Create New File, назовите его ТОЧНО ТАКЖЕ (в нашем случае kovriexample.md), вставьте из буфера и сохраните. Да я знаю, вставленный текст не на испанском. Он может быть переведен на испанский позже. Сайт просто не соберется, пока в каждой отдельно взятой языковой папке не появится одинаково названный файл, поэтому мы вставляем текст заглушку (просто оригинальный текст) до тех пор, пока какой-нибудь крутой переводчик не придет и не переведет его.

    Да, вы не зря насторожились. Вам требуется повторить все вышеописанные действия для всех языковых папок. Когда закончите, будет здорово, если бы быстренько пробежитесь по папкам языков и убедитесь, что в каждой есть ваш файл. В нашем примере убедитесь, что каждая папка содержит kovriexample.md. Все проверили, тогда пришло время для следующего шага.

    Отлично, продолжаем, в папке _il8n есть не только языковые папки, но и несколько файлов .yml для каждого языка. И тут нам снова надо поработать. Открываем первый, допустим, это en.yml, и находим раздел внизу, подписанный как titles. Создайте новую строку под существующими названиями страниц и отступите два пробела (так, чтобы она стала на одном уровне с другими). Уникальное имя, которое вы создали в титульном листе в разделе title (в нашем примере titles.example), просто вставьте его ПОСЛЕ titles в строку, после этого слова двоеточие и пробел (для нашего примера мы просто вставим example: ). Да, двоеточие и пробел обязательны. Jekyll иногда может быть очень придирчивым. После этого введите расширенный заголовок вашей страницы. Я выбрал 'Kovri Пример страницы' для моего примера.

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

    2.2.5 Навигация (и еще немного про поддержку нескольких языков)

    Верите вы или нет, но мы почти закончили. Просто надо сделать еще одну мелочь. Перейдите в корень файловой системы (сайта) и найдите папку _data/lang. Там все те же языковые папки, в каждой из которых один только файл navigation.yml. На этом шаге необходимо указать вашу страницу где-нибудь в навигации. Откроем, например, файл en/navigation.yml. Вам необходимо определить подходящее место для вашей страницы в навигации и поместить ее тут.

    Примечание:
    Мы все склонны думать, что наш контент достоин быть в первом (верхнем) уровне навигации (или одним из основных элементов навигации). Если вы не уверены наверняка, обсудите это с сопровождающим веб-сайт, чтобы убедиться, что вашей странице необходимо быть в верхних уровнях навигации. Если нет, не вставляйте ее туда.


    Допустим, что kovri-example.html это страница, которая рассказывает о том, как получить Kovri и начать с ним работать для новичков. Возможно, лучшее место для ее в разделе 'Начало работы(Get Started)'. Найдите title: Get Started, перейдите в subfolderitems и скопируйте код от одного тире до другого, вставьте его в конце раздела, но перед следующим title:
    Код:
    - page: General
      url: contributing.html
    
    • измените имя и url на соответствующее вашей странице. Разберем подробнее:
    • page: Это то, как ваша страница будет называться в навигации или выпадающем меню. Для нашего примера поменяем имя на Kovri Пример
    • url: это url, который вы создали в самом начале процесса. Для нашего примера это kovri-example.html.
    Код:
    - page: Kovri Пример
      url: kovri-example.html
    
    УБЕДИТЕСЬ, ЧТО ТИРЕ СТОИТ В САМОМ НАЧАЛЕ СТРОКИ! Тупое форматирование? Да, но Jekyll часто не собирается, если тут будет хоть один пробел. Шутки в сторону. Выполните это условие.

    Скопируйте полученный результат в каждый файл navigation.yml языковых папок. Кто-то придет и переведет их позже.

    Отличная работа! Вы только что создали страницу и внесли вклад в Kovri. Дважды все проверьте и подайте запрос (pull request) на добавление ваших трудов в сайт.

    2.3 Для перевода

    Если вы хотите помочь с переводом страниц, которые уже существуют на других языках, вам было бы полезно ознакомиться с предыдущим разделом (2.2 Изменить или добавить страницы(Markdown)) и пройти по шагам как будто вы создаете страницу, чтобы понять процесс и структуру файлов. Но не переживайте, я дам инструкции ниже.

    Предположим, мы собираемся перевести Building Page на испанский.

    2.3.1 Скопируйте (fork) этот код!

    Копируем(Fork) репозиторий сайта Kovri и рекурсивно клонируем с помощью команды `$ git clone --recurisve https://github.com/monero-project/kovri-site`.

    Прежде всего, вам нужно знать, как использовать Markdown. Это в основном промежуточный язык, который позволяет людям без знания HTML просто написать, и это будет преобразовано в HTML для вас. Можете посмотреть отличную шпаргалку с примерами здесь. Если вам требуется больше помощи, Google и YouTube отличные ресурсы для этого.

    2.3.2 Для начала

    Начнем с перехода в папку doc и найдем там страницу, которую хотим перевести, в нашем случае building.html. Откройте файл и обратите внимание на содержимое между {% %}.
    Код:
    {% tf building.md %}
    
    для нашего примера это building.md.

    Запомните это имя файла и переходите в папку _i18n. Тут вы увидите несколько папок и файлов в зависимости от поддерживаемых языков в данный момент.

    Вам нужно открыть оригинальный файл из подходящей языковой папки (который вероятно будет на английском, а значит в папке en ) в другой вкладке или окне, чтобы вы могли переводить, хотя окружение у каждого переводчика свое. Сделайте это по своему, как вам удобно. :) Найдите файл с тем же именем, которое вы нашли ранее (в нашем случае: building.md), и откройте его.

    Держите эту вкладку или окно открытым и откройте другое. Найдите папку, которая представляет ваш язык (не знаете какая? свяжитесь со мной и я подскажу) и откройте ее. Найдите файл с таким же именем ((building.md в нашем примере) и откройте его.

    2.3.3 Переведи!

    Примечание: все переводы документации выполняются в репозитории kovri-docs по адресу https://github.com/monero-project/kovri-docs

    Можете оставить все форматирование без изменений и просто изменить слова после или между (форматированием). Так для нашего примера можете взять такой текст:

    Код:
    ## Friend
    
    и превратить его в этот
    Код:
    ## Amigo
    
    или такой:
    Код:
    *friend*
    
    в этот
    Код:
    *amigo*
    
    Опять же будет намного проще, если вы сможете распознать markdown форматирование и пропустить его.

    Отлично, настало время блеснуть. Начинайте переводить!

    2.3.4 Наведение порядков

    И еще пара вещей! Заголовок страницы (центральная копия, которая открывает страницу после навигации) еще не изменен. Измените его, перейдя обратно в папку _i18n и отыскав файл .yml для вашего языка. В нашем случае es.yml. Откройте его и найдите раздел названный titles. Найдите имя страницы, над которой работаете (в нашем случае building) и измените текст после на перевод. Сохранить, закрыть. Вуаля, заголовок изменен.

    Перейдите в корневую папку, а затем в папку _data/lang. Перейдите в папку соответствующую вашему языку и откройте файл navigation.yml. Найдите URL страницы, которую вы переводите (в нашем примере building.html). Сразу над url должен быть параметр page:. Переведите значение параметра page:. Это изменит отображение страницы в навигации по сайту для данного языка.

    И на этом все! Выбранная страница теперь полностью переведена. Спасибо, что сделали Kovri доступнее для широкой, глобальной аудитории.

    3. Выбираем макет

    Тут перечислены различные макеты, которыми вы можете воспользоваться, а также описание того, для чего они предназначены. Вы можете создавать свои макеты, для этого вам необходимо следовать инструкциям раздела 2.1 "Изменить или добавить страницы(Markdown)"

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

    3.1 Макеты

    В настоящий момент доступны следующие макеты:
    • default: это макет представляет собой одиночный информационный блок в полную ширину, как тот что можно увидеть на [стартовой странице Kovri](https://getkovri.org). Ничего необычного. Подойдет большинству текстовых страниц.

    Больше макетов будет добавлено впоследствии

    4. Вопросы & Контакты

    Это все, что вам может понадобиться. Будет также выпущен документ об объектах(assets) для всего фреймворка в целом, который покажет, как создавать свои макеты простым копированием и вставкой прямо из документа. Текущий документ будет дополнен ссылкой после выхода документа об объектах.

    Не стесняйтесь обращаться к нам с любыми вопросами, касающимися перевода, создания страниц, содержимого, markdown, jekyll, html/css и всего остального. Опять же вы можете связаться с нами на IRC канале #kovri-dev.

    Спасибо, что являетесь частью сообщества Monero и вносите свой вклад. Эта монета все сильнее благодаря вашей помощи.

    Источник: Instructions to edit Kovri website

    Перевод:
    MoneroRus (@MoneroRus)
    Редактирование:
    Mr. Pickles (@v1docq47)
    Коррекция:
    Kukima (@Kukima)
     
    #1 MoneroRus, 13 июн 2018
    Последнее редактирование модератором: 22 июн 2018
    TheFuzzStone нравится это.
  • О нас

    Наш сайт является одним из уникальных мест, где русскоязычное сообщество Monero может свободно общаться на темы, связанные с этой криптовалютой. Мы стараемся публиковать полезные мануалы и статьи (как собственные, так и переводы с английского) о криптовалюте Monero. Если вы хорошо владеете английским (или можете писать собственные статьи/мануалы) и хотите помочь в переводах и общем развитии Monero для русскоязычной аудитории - свяжитесь с одним из администраторов.