Какво поддържа Markdown в QGIS.бг докс?

QGIS.бг докс е написан изцяло в текстовия формат Markdown. Освен базовия синтаксис, в този QGIS.бг докс се използват и редица разширения на езика, които позволяват по-описателно съдържание.

Разширения специално за QGIS.бг

Икони от QGIS

Поради тенденцията съдържанието на сайта да съдържа все повече съдържание свързано с QGIS, често се налага иконите от сайта на QGIS да се унагледят в ръководството. За целта има специално създаден Markdown таг, който е във формат :i:qgis:<ICON_FILENAME>:, където <ICON_FILENAME> е името на файла директно от хранилището на QGIS.

Пример: икони от QGIS

ИзходMarkdown

Иконка филтър

Иконка карта

Иконка филтър :i:qgis:mActionFilter:

Иконка карта :i:qgis:svgbase/worldmap:

Общодостъпни Markdown разширения

Следните разширения за Markdown са често използвани в различни проекти извън qgisbg и са разрешени за използване тук по подразбиране.

Мета данни (meta_data)

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

Пример: мета данни

Markdown

---
title: Markdown в QGIS.бг докс
tags: qgis.бг, докс
---

Специални символи (smarty)

Някои специални символи нямат възможност да бъдат въведени директно от клавиатурата. Такива са например триеточието (…), както и дългите тирета (– или —).

Пример: специални символи

ИзходMarkdown

ASCII	заместител	име
...	…	триеточие (ellipsis)
--	–	тире
---	—	много дълго тире

ASCII  | заместител | име
-------|------------|---------------------
\.\.\. | ...        | триеточие (ellipsis)
\-\-   | --         | тире
\-\-\- | ---        | много дълго тире

Бележки под линия (footnotes)

Бележките под линия са удобен начин за предоставяне на допълнителна информация, без накъсване на контекста на изречението с линкове или скоби. Употребата им в QGIS.бг се окуражава.

Пример: бележки под линия

ИзходMarkdown

Бележки¹ имат етикет² и съдържание на етикета ³.

Бележки[^1] имат етикет[^@#$%] и съдържание на етикета [^or_a_name].

[^1]: Бележка под линия.
[^@#$%]: и още бележки под линия за: "@#$%".
[^or_a_name]: и още бележки под линия за: "or_a_name".

Забележка!

Демото на този плъгин се намира в края на страницата.

Речници (definition_lists)

Макар и рядко, може да се наложи списък с дефиниции. В такива ситуации речниците са от изключителна полза.

Пример: речници

ИзходMarkdown

Ябълка

Най-вкусен този представител на розоцветни е на кекс.

Портокал

Тази година цитруси има не само на Коледа.

Ябълка
:   Най-вкусен този представител на розоцветни е на кекс.

Портокал
:   Тази година цитруси има не само на Коледа.

Таблици (tables)

Пример: таблици

ИзходMarkdown

Добре форматирата таблица изглежда по този начин.

първо заглавие 1	второ заглавие 2
клетка 1.1	клетка 2.1
клетка 1.2	клетка 2.2

Но всъщност таблиците може да не бъдат с перфектно подредени колони (виж Markdown). Всяка колона може да бъде подравнена в избрана от нас посока. Например всички колони с числа (суми, бройки и пр.) се подравняват задължително вдясно.

ляво подравнен текст	дясно подравнен текст	централно подравнен текст
клетка 1.1	клетка 2.1	клетка 3.1
клетка 1.2	клетка 2.2	клетка 3.2

Добре форматирата таблица изглежда по този начин.

първо заглавие 1 | второ заглавие 2
-----------------|-----------------
клетка 1.1       | клетка 2.1
клетка 1.2       | клетка 2.2

Но всъщност таблиците може да не бъдат с перфектно подредени колони. А и всяка колона може да бъде подравнена в избрана от нас посока. Например всички колони с числа (суми, бройки и пр.) се подравняват задължително вдясно.

ляво подравнен текст   | дясно подравнен текст |централно подравнен текст|
-----|-------:|:------:
клетка 1.1 | клетка 2.1 | клетка 3.1
клетка 1.2 | клетка 2.2 | клетка 3.2

Разширения от pymdownx

Горен индекс и подчертан текст (pymdownx.caret)

Символът ^ (циркумфлекс или колибка) може да се използва за горен индекс или подчертаване на текст.

Пример: горен индекс и подчертан текст

ИзходMarkdown

Подчертан текст с две колибки

H²0

текст^{горен индекс}

^^Подчертан текст с две колибки^^

H^2^0

текст^горен\ индекс^

Долен индекс и зачеркнат текст (pymdownx.tilde)

Символът ~ (тилда или вълничка) може да се използва за долен индекс или зачеркване на текст.

Пример: долен индекс и зачеркнат текст

ИзходMarkdown

зачеркнат текст

CH₃CH₂OH

текст_{долен индекс}

~~зачеркнат текст~~

CH~3~CH~2~OH

текст~долен\ индекс~

Клавишни комбинации (pymdownx.keys)

Често за описване на дадана функционалност използваме и клавишни компинации и този таг спомага за повишаване на четимостта. Списък с имената на бутоните може да откриете тук.

Пример: клавишни комбинации

ИзходMarkdown

Ctrl+Alt+Del.

++ctrl+alt+delete++

Внимание!

Изписването на имената на бутоните задължително се случва с малки букви на латиница.

Емоджита (pymdownx.emoji)

Пълен списък на поддържаните емоджита и техните имена може да откриете тук.

Пример: емоджита

ИзходMarkdown

:smile: :heart: :earth_africa:

Специални символи (pymdownx.escapeall)

Понякога се налага да изпишем някои специални символи, които обаче са част от синтаксиса на Markdown. За целта пред всеки един символ може да постави наклонена черта \, с което символа губи специалното си значение в Markdown.

пример: специални символи

ИзходMarkdown

Този пример е такъв. Този `пример` обаче не.

Този `пример` е такъв. Този \`пример\` обаче не.

Автоматични връзки (pymdownx.magiclinks)

пример: автоматични връзки

ИзходMarkdown

• Когато показваме самият линк, просто го принтираме така: https://google.com.
• Дори и имейли адреси: fake.email@email.com.

- Когато показваме самият линк, просто го принтираме така: https://google.com.
- Дори и имейли адреси: fake.email@email.com.

Детайли (pymdownx.details)

Понякога особена част от съдържанието трябва да бъде подчертана на читателя. Блоковете със забележки трябва да се използват само с фиксираните заглавия по-долу и да се използват само в описаните ситуации.

Пример: детайли

ИзходMarkdown

Забележка!

Отворено съдържание заради плюсчето в ???+

Вложени детайли!

И още повече информация тук.

Пример

Съдържа примери за употреба.

Забележка!

Допълнително уточняващо съдържание, на което потребителите да обърнат внимание.

Важно!

Допълнително уточняващо съдържание, което е от особена важност за читателя.

Успех!

Описва ситуация или краен резултат, които се смятат за успешен завършек.

Внимание!

Допълнително уточняващо съдържание, което за риск от повреда на данните, програмата или системата.

Опасност!

Допълнително уточняващо съдържание, което за риск от непоправима повреда на данните, програмата или системата.

???+ "Забележка!"
    Отворено съдържание заради плюсчето в `???+`

    ??? danger "Вложени детайли!"
        И още повече информация тук.


???+ example "Пример"
    Съдържа примери за употреба.

???+ note "Забележка!"
    Допълнително уточняващо съдържание, на което потребителите да обърнат внимание.

???+ important "Важно!"
    Допълнително уточняващо съдържание, което е от особена важност за читателя.

???+ success "Успех!"
    Описва ситуация или краен резултат, които се смятат за успешен завършек.

???+ warning "Внимание!"
    Допълнително уточняващо съдържание, което за риск от повреда на данните, програмата или системата.

???+ danger "Опасност!"
    Допълнително уточняващо съдържание, което за риск от непоправима повреда на данните, програмата или системата.

Табове (pymdownx.tabs)

Пример: табове

ИзходMarkdown

Таб 1Таб 2

Всеки таб започва с ===, последвано от заглавието му в двойни кавички, на пример === Таб 1.

Съдържанието е един отстъп навътре и може да съдържа всякакъв Markdown.

Още съдържание в табовете.

• елемент а
• елемент б

Таб АТаб Б

Започването на нова група от табове може да стане с ===!.

Още съдържание.

=== "Таб 1"
    Всеки таб започва с `===`, последвано от заглавието му в двойни кавички, на пример `=== Таб 1`.

    Съдържанието е един отстъп навътре и може да съдържа всякакъв Markdown.

=== "Таб 2"
    Още съдържание в **табовете**.

    - елемент а
    - елемент б

===! "Таб А"
    Започването на нова група от табове може да стане с `===!`.

=== "Таб Б"
    ```
    Още съдържание.
    ```

Внимание!

Използването на табове има един огромен недостатък, а именно че не цялото съдържание на страницата е видимо във всеки един момент. Табовете трябва да са използват само за взаимноизключващи се елементи, както в случая за комбинацията пример и Markdown.

Употреба

Употребата на табо е приета само и единствено при показване на примери и изходния код към тях. В този случай съдържанието се организира по следния начин:

???+ example "Пример: табове"

    === "Изход"
        Hello world!
    === "Python"
        ```python
        print('Hello world!')
        ```

---

1. Бележка под линия. ↩

2. и още бележки под линия за: “@#$%”. ↩

3. и още бележки под линия за: “or_a_name”. ↩