Vue code markup

English | Русский

Данный плагин создавался для документирования кода. Обычно для этого используется "storybook", но это не подходит для тех случаев, когда человек для которого этот код документируется не является frontend-разработчиком. Он в "storybook" не разберётся. Мне нужно было написать один компонент для "vue.js" и описать как он работает для backend разработчика, чтобы он мог им пользоваться. По сути это была детальная инструкция по использованию, основам "vue.js", со множеством примеров.

В качестве редактора я использую "Visual Studio Code", мне очень нравится тема "darcula", её я и взял в качестве основной для моего плагина. В будующем я планирую сделать другие темы: "monokai", "gitHub theme" и др. Если у вас стоит задача по документированию кода, то я думаю, что мой плагин вам подойдёт. Есть и другие плагины позволяющие вывести код, но там по сути 2-3 цвета, и они не яркие. С моим плагином, ваша документация станет ярче.

Основной упор будет делаться на написание документации для vue.js компонентов.

Глобальная установка, подключение плагина

Для установки моего плагина необходимо иметь установленный node.js и npm последней версии. В терминале нужно ввести следующую команду:

npm install vue-code-markup

После установки, если никаких ошибок не возникнет, нужно подключить мой плагин следующим способом:

import { createApp } from 'vue';
import App from './App.vue';
import CodeMarkup from 'vue-code-markup';
import 'vue-code-markup/lib/style.css';

const app = createApp(App);
app.use(CodeMarkup);
app.mount('#app');

Возможно подключить только CSS и отдельные компоненты, как это сделать я опишу ниже.

Главные компоненты

Это компоненты в которые должны быть обёрнуты все остальные компоненты, без них вся стилизация не имеет никакого смысла. Это "code-markup" и "code-line". Сode-markup - это самый главный компонент, в него должны быть обернуты все остальные компоненты, по сути это окно редактора, в котором находятся строки кода и примеры кода. Сode-line - это линия, или строка с кодом, все остальные компоненты должны быть обёрнуты им.

Компонент code-markup

Это самый главный компонент, он служит обёрткой для всех остальных компонентов. Если вы не хотите делать полную установку, то подключить его можно следующим способом:

<template>
  <code-markup>
    <!-- component content -->
  </code-markup>
</template>

<script setup>
  import { CodeMarkup } from 'vue-code-markup';
  import 'vue-code-markup/lib/style.css';
</script>

Я бы вам советовал посмотреть документаци на github pages, там можно поменять параметры и посмотреть, что изменится. Данный компонент имеет следующие входные параметры:

isHeader - данный параметр отвечает за отображение заголовка окна с кодом. Если вы собираетесь отображать заголовок, то данный параметр можно не задавать, он по умолчанию равен "true".

header - заголовок окна с кодом. По умолчанию не имеет значения.

isCount - данный параметр отвечает за отображение номера строки. Если его не задать, то строки будут пронумерованы, по умолчанию равен "true".

lineCount - данный параметр отвечает за то, сколько строк отображать. В него нужно передавать числа, если нужно отобразить все строки, то нужно задать значение "auto", или вообще не задавать данный параметр. По умолчанию задано значение "auto".

textBold - данный параметр отвечает за "толщину шрифта". По умолчанию задано "false".

headerBold - данный параметр отвечает за толщину шрифта заголовка окна с кодом. По умолчанию задано "false".

code - в данный параметр передаётся код, который нужно будет скопировать в буфер обмена. Это может быть как строка, так и объект.

title - подсказка, которая будет появляться при наведении на иконку "скопировать текст". По умолчанию задано значение "Copy code to clipboard". Как правило это нужно для интернационализации.

successfulText - подсказка, которая будет появляться при наведении на иконку "скопировать текст" после того, как текст будет скопирован. По умолчанию задано значение "The code is copied to the clipboard". Как правило это нужно для интернационализации.

errorText - подсказка, которая будет появляться при наведении на иконку "скопировать текст" в случае возникновении ошибки (если текст не получится скопировать). По умолчанию задано значение "An error occurred while copying the code to the clipboard". Как правило это нужно для интернационализации.

Компонент code-line

По сути это линия или строка с кодом. Элементы кода должны находиться в этом компоненте. Подключается он следующим способом:

<template>
  <code-markup>
    <code-line>
      <!-- component content -->
    </code-line>
  </code-markup>
</template>

<script setup>
  import { CodeMarkup, CodeLine } from 'vue-code-markup';
  import 'vue-code-markup/lib/style.css';
</script>

Данный компонент имеет следующие входные параметры:

new - в Visual Studio Code, когда добавляется новая строка, она отображается правой вертикальной линией, которая разделяет номер строки и текст строки. Данный параметр отображает эту линию. Вертикальная линия будет заметна только в том случае, если номера строк отображаются (включён параметр is-count). По умолчанию данный параметр отключен, те имеет значение false.

active - в Visual Studio Code активная строка отличается от других строк background-ом. Данный параметр включает background для строки. По умолчанию данный параметр отключен, те имеет значение false.

visibleCopy - по умолчанию правый внутренний отступ для строки равен 5px. Возможна такая ситуация, что строк не много, и они достаточно длинные, таким образом кнопка "скопировать текст" будет перекрывать текст строки. При включении данного параметра будет появляться больший правый отступ, так, что можно будет прочитать текст. По умолчанию данный параметр отключен, те имеет значение false.

evel-2 - level-8 - код имеет определённую вложенность. Данные входные параметры нужны для того, чтобы сделать соответствующий отступ. Всего я предусмотрел 8 уровней вложенности, больше делать я смысла не вижу.

Компоненты для разметки документа

Если сравнивать с HTML, то эти компоненты можно назвать тегами из которых состоит документ. Все эти компоненты имеют один входной параметр, он называется "code", для удобства ими можно обернуть текст кода, но я бы посоветовал всё таки пользоваться входным параметром. Если он задан, то выведится содержимое входного параметра "code".

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

Общие компоненты разметки документа:

Общими для блока шаблона, скриптов, и стилей являются следующие компоненты:

• MuText - это обычный текст, в разметке это то, что заключено в одинарные, или двойные кавычки.
• MuNumber - это все цифры, которые встречаются в разметке.
• MuComment - это все комментарии, которые встречаются в разметке.
• MuType - это типовой текст. Если вы обернёте какой-нибудь текст компонентом "code-line", то обёрнутый текст будет того же цвета, что и цвет компонента "MuType".

Пример подключения общих компонентов:

<template>
  <code-markup>
    <code-line>
      <mu-text code="Some text" />
    </code-line>
    <code-line>
      <mu-number code="1234" />
    </code-line>
    <code-line>
      <mu-comment code="// Some comment" />
    </code-line>
    <code-line>
      <mu-type code="Type code" />
    </code-line>
  </code-markup>
</template>

<script setup>
  import {
    CodeMarkup,
    CodeLine,
    MuText,
    MuNumber,
    MuComment,
    MuType,
  } from 'vue-code-markup';
  import 'vue-code-markup/lib/style.css';
</script>

Компоненты для блока шаблона

Это компоненты, которые находятся в блоке "template". Также к этим компонента относятся сами блоки "template", "script", "style". Таких компонентов всего лишь 2:

• MuTag - это теги блока "template", а также названия блоков "template", "script", "style".
• MuAttr - это атрибуты тегов, к примеру "setup" для блока "script".

Пример подключения компонентов шаблона:

<template>
  <code-markup>
    <code-line>
      <mu-tag code="<script" />
      <mu-attr code=" setup" />
      <mu-tag code=">" />
    </code-line>
    <code-line>
      <mu-tag :code="`</${'script'}>`" />
    </code-line>
  </code-markup>
</template>

<script setup>
  import {
    CodeMarkup,
    CodeLine,
    MuTag,
    MuAttr,
  } from 'vue-code-markup';
  import 'vue-code-markup/lib/style.css';
</script>

Компоненты для блока скриптов

Это компоненты которые находятся в блоке "script". Ниже я их перечислю:

• MuKey - если нужно отобразить объект, то для написания ключа объекта используется этот компонент.
• MuKeyWords - это ключевые слова, в JS таковыми словами являются import, export, const, let, var, fucntion и тд.
• MuVariable - если нужно отобразить название переменной, то используется этот компонент.
• MuFunction - если нужно отобразить название функци, то используется этот компонент.

Пример подключения компонентов для блока скриптов:

<template>
  <code-markup>
    <code-line>
      <mu-key-words code="const " />
      <mu-variable code="someObject" />
      =
      <mu-key-words code="ref" />
      ({
    </code-line>
    <code-line level-2>
      <mu-key code="key" />
      : value
    </code-line>
    <code-line>
    });
    </code-line>

    <code-line />

    <code-line>
      <mu-key-words code="function "/>
      <mu-function code="exampleFunction() "/>{
    </code-line>
    <code-line level-2>
      <mu-key-words code="return "/>
      <mu-variable code="someObject"/>
      ;
    </code-line>
    <code-line>
    }
    </code-line>
  </code-markup>
</template>

<script setup>
  import {
    CodeMarkup,
    CodeLine,
    MuKey,
    MuKeyWords,
    MuVariable,
    MuFunction,
  } from 'vue-code-markup';
  import 'vue-code-markup/lib/style.css';
</script>

Компоненты для блока стилей

Это компоненты которые находятся в блоке "style". Ниже я их перечислю:

• MuStyleClass - этот компонент используется для вывода классов.
• MuStyleId - этот компонент используется для вывода id-ов.
• MuStyleTag - этот компонент используется для вывода тегов.
• MuStyleKey - если нужно вывести код препроцессора (less или sass), то этот компонент нужен для создания вложенных правил. К примеру, если у нас есть класс ".book", и в нём лежит CSS компонент "&-item", то "&-item" нужно вывечти через "MuStyleKey".
• MuStyleParam - в этот компонент нужно будет положить свойства CSS элемента. Если объяснять более подробно, то этими свойствами являются margin, padding, font-size и тд.
• MuStyleUnitMeas - этот компонент нужен для вывода единиц измерения (em. rem, px и тд).
• MuStyleAmpersand - этот компонент нужен для вывода амперсанда (&).
• MuStyleCurlyBrace - этот компонент нужен для вывода фигурных скобок.

Данные компоненты подключаются следующим способом:

<template>
  <code-markup>
    <code-line>
      <mu-style-id code="#books-list {" />
    </code-line>
    <code-line level-2>
      <mu-style-param code="margin" />:
      <mu-number code=" 1" />
      <mu-style-unit-meas code="em" />
      <mu-number code=" 0 " />
      <mu-number code="2.5" />
      <mu-style-unit-meas code="em" />;
    </code-line>
    <code-line>
      <mu-style-id code="}" />
    </code-line>
    <code-line />
    <code-line>
      <mu-style-class code=".books-list {" />
      </code-line>
    <code-line level-2 >
      <mu-style-param code="line-height" />:
      <mu-number code=" 1.2" />;
      </code-line>
    <code-line />
    <code-line level-2 >
      <mu-style-tag code="h3 {" />
    </code-line>
    <code-line level-3 >
      <mu-style-param code="font-size" />:
      <mu-number code="1.2" />
      <mu-style-unit-meas code="em" />;
    </code-line>
    <code-line level-3 >
      <mu-style-param code="margin" />:
      <mu-number code=".4" />
      <mu-style-unit-meas code="em" />;
      <mu-number code=" 0 " />
      <mu-number code=".3" />
      <mu-style-unit-meas code="em" />
    </code-line>
    <code-line level-2 >
      <mu-style-tag code="}" />
      </code-line>
    <code-line />
    <code-line level-2 >
      <mu-style-ampersand code="&" />
      <mu-style-key code="-item" />
      <mu-style-curly-brace code=" {" />
    </code-line>
    <code-line level-3 >
      <mu-style-param code="margin" />:
      <mu-number code="1.5" />
      <mu-style-unit-meas code="em" />
      <mu-number code=" 0 " />;
    </code-line>
    <code-line level-2 >
      <mu-style-curly-brace code="}" />;
    </code-line>
    <code-line>
      <mu-style-class code="}" />
    </code-line>
  </code-markup>
</template>

<script setup>
  import {
    CodeMarkup,
    CodeLine,
    MuStyleClass,
    MuStyleId,
    MuStyleTag,
    MuStyleKey,
    MuStyleParam,
    MuStyleUnitMeas,
    MuStyleAmpersand,
    MuStyleCurlyBrace,
  } from 'vue-code-markup';
  import 'vue-code-markup/lib/style.css';
</script>

Слоты

Для данного раздела стоит начать сразу с примера, так будет понятнее:

<template>
  <code-markup>
    <template #default>
      <!-- Сюда вставляется код по умолчанию, если никаких других шаблонов не задано -->
    </template>
    <template #header>
      <!-- Сюда вставляется заголвок окна с кодом -->
    </template>

    <!-- Ниже находятся слоты для иконок "скопировать текст", "текст удачно скопирован" и иконка когда произошла ошибка во время копирования текста в буфер обмена -->
    <template #copy>
      <!-- Сюда вставляется иконка "скопировать текст" -->
    </template>
    <template #success>
      <!-- Сюда вставляется иконка, когда текст удачно скопирован в буфер обмена -->
    </template>
    <template #error>
      <!-- Сюда вставляется иконка, если произошла ошибка во время копирования текста в буфер обмена -->
    </template>
  </code-markup>
</template>

Я думаю, пример выше отлично показывает как пользоваться слотами, но всё же ниже я их опишу.

• default - это слот по умолчанию. Если вам не нужны другие слоты, то это будет слот когда вы оборачиваете что-то компонентом "code-markup".
• header - это слот для заголовка окна с кодом. Для его отображения входной параметр "isHeader" должен быть установлен в "true". Если задан входной параметр "header", то будет выведен он, а не содержимое слота. Как правило данный слот нужен для того, чтобы вставить на место заголовка окна с кодом текст с иконкой, какое-то HTML содержимое, какой-нибудь компонент VUE.js, привязать к заголовку какую-нибудь логику. На данной странице, я через данный слот делаю tab-ы.

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

• copy - данный слот нужен для того, чтобы заменить иконку "скопировать текст". В него можно вставить картинку, или svg-ку. Картинка или svg-ка займет всю ширину, высоту я не трогаю. Лучше сюда вставить квадратную иконку. Место для этого слота будет иметь ширину и высоту "1em".
• success - данный слот нужен для того, чтобы заменить иконку когда текст успешно скопирован в буфер обмена. В него так-же можно вставить картинку, или svg-ку. Картинка или svg-ка займет всю ширину, высоту я не трогаю. Лучше сюда вставить квадратную иконку. Место для этого слота будет иметь ширину и высоту "1em".
• error - данный слот нужен для того, чтобы заменить иконку когда произошла ошибка во время копирования текста в буфер обмена. В него так-же можно вставить картинку, или svg-ку. Картинка или svg-ка займет всю ширину, высоту я не трогаю. Лучше сюда вставить квадратную иконку. Место для этого слота будет иметь ширину и высоту "1em".