diff --git a/en/_images/leading.jpg b/en/_images/leading.jpg new file mode 100644 index 00000000..37dfaa38 Binary files /dev/null and b/en/_images/leading.jpg differ diff --git a/en/_images/overview.jpg b/en/_images/overview.jpg new file mode 100644 index 00000000..a169c85b Binary files /dev/null and b/en/_images/overview.jpg differ diff --git a/en/_images/overview_landing_black.jpg b/en/_images/overview_landing_black.jpg new file mode 100644 index 00000000..a3c04cac Binary files /dev/null and b/en/_images/overview_landing_black.jpg differ diff --git a/en/_images/overview_landing_white.jpg b/en/_images/overview_landing_white.jpg new file mode 100644 index 00000000..8ade98f8 Binary files /dev/null and b/en/_images/overview_landing_white.jpg differ diff --git a/en/_images/terms_sample.png b/en/_images/terms_sample.png new file mode 100644 index 00000000..21609301 Binary files /dev/null and b/en/_images/terms_sample.png differ diff --git a/en/_images/user-settings.png b/en/_images/user-settings.png new file mode 100644 index 00000000..f131d416 Binary files /dev/null and b/en/_images/user-settings.png differ diff --git a/en/_images/user_settings.jpg b/en/_images/user_settings.jpg new file mode 100644 index 00000000..98e843ac Binary files /dev/null and b/en/_images/user_settings.jpg differ diff --git a/en/_includes/file.md b/en/_includes/file.md new file mode 100644 index 00000000..87702b48 --- /dev/null +++ b/en/_includes/file.md @@ -0,0 +1 @@ +Fake file \ No newline at end of file diff --git a/en/_includes/plugins.md b/en/_includes/plugins.md new file mode 100644 index 00000000..006431c5 --- /dev/null +++ b/en/_includes/plugins.md @@ -0,0 +1,19 @@ +| Plugin name | Description | Parameters | Added
by default | +|--------------| --- | --- | --- | +| **Anchors** | Automatically generate [anchors for headers](../syntax/base.md#headers) | `extractTitle`: Consider the first level header
(type: bool, default value: false)

`supportGithubAnchors`: Generate additional anchors compatible with GitHub
(type: bool, default value: false) | + | +| **code** | Display the copy button in [code blocks](../syntax/code.md#block) | - | + | +| **Cut** | Support for the [cut](../syntax/cuts-tabs.md#cuts) markup | - | + | +| **Deflist** | Support for the [definition list](../syntax/lists.md#terms) markup | - | + | +| **File** | Support for the [file objects](../syntax/links.md#files) markup | `fileExtraAttrs`: additional attributes for the link | + | +| **Tasks list** | Support for the [tasks list](../syntax/additional.md#tasks-list) | `divClass`: classname for div wrapping the checkbox
(type: string, default value: checkbox)

`idPrefix`: prefix for checkbox id
(type: string, default value: checkbox) | - | +| **Images** | Add [images](../syntax/media.md#images) | `assetsPublicPath`: Path to icons
(type: string, default value: /) | - | +| **Imsize** | Set the image size | - | - | +| **Includes** | Reuse content in a document | `getVarsPerFile`: A function that returns calculated variables using the path to the file
(type: function, default value: -) | - | +| **Links** | Expand [link syntax](../syntax/links.md) | - | - | +| **Meta** | Add [metadata](../syntax/meta.md#meta) to the beginning of files | - | + | +| **Notes** | Support for the [note](../syntax/notes.md) markup | `lang`: A language for displaying the note type
(type: string, default: ru) | + | +| **Sup** | Output text as [superscript](../syntax/base.md#line) | - | + | +| **Table** | Support for [multiline tables](../syntax/tables/multiline.md) | - | + | +| **Tabs** | Support for the [tab](../syntax/cuts-tabs.md#tabs) markup | - | + | +| **Video** | Add a [video](../syntax/media.md#video) | - | + | + diff --git a/en/about.md b/en/about.md new file mode 100644 index 00000000..d7602bf1 --- /dev/null +++ b/en/about.md @@ -0,0 +1,30 @@ +# Diplodoc + +Diplodoc Platform is open platform for work with your documentation in accordance with "Documentation as a Code" paradigm. +Simple and comfortable solution for everyone. + +## Advantages of the platform +### Easy to use +- Work with documents in the same way as with code +- Minimal efforts for deployment and integration + +### Speed +- Fast validation, build and deploy for your projects +- Easy integration with your developement pipelines + +### Full support of Markdown +- Simple syntax +- Easy learning +- Concentration on content creation, not deployment +- Rich functionality + +### Support for complex Documentation projects +- Customization and localization +- “One Source” support +- Add more functionality with plugins even + +### Supports for autogenerated documentation +- OpenAPI support out of the box +- Custom includer’s interface for any kind of autogenerated docs (JavaDoc, etc..) + + diff --git a/en/changelog.md b/en/changelog.md new file mode 100644 index 00000000..8decd056 --- /dev/null +++ b/en/changelog.md @@ -0,0 +1,343 @@ +# Revision history + +## December 2022 + +### yfm-docs + +#### 2.0.0 + +- [New Includers Interface](./project/toc.md#includers) +- [Generic Includer](./project/toc.md#includers-generic) +- [Open API Includer](./project/toc.md#includers-open-api) +- [Unarchive Includer](./project/toc.md#includers-unarchive) +- [Source Docs Includer](./project/toc.md#includers-source-docs) + +## November 2022 + +### yfm-docs + +#### 1.31.0 + +- Added support for [definitions](./syntax/term.md). + +### yfm-transform + +#### 2.16.0 + +- Added support for inline markup in [task lists](./syntax/additional.md#tasks-list) + +#### 2.15.0 + +- Added `linkifyTlds` option that allows configure tld for the linkify plugin. + +## September 2022 + +### yfm-docs + +#### 1.26.0 + +- services/leading: add [substitutions and conditional operators support](./project/leading-page.md#subtitudes) on leading page for title and description. +- services/tocs: add [substitutions and conditional operators support](./project/toc.md#subtitudes) in document title. + +#### 1.24.0 + +- includers/openapi: allows autogeneration from openapi specification and inclusion into the main document. + [Open API](./project/toc.md#open-api) + +### yfm-transform + +#### 2.14.0 + +- Added sanitizing of generated HTML. Disabled by default. Parameter to enable: `needToSanitizeHtml: true`. You can override the default settings via the `sanitizeOptions` parameter. + +#### 2.13.0 + +- Added syntax for [definitions](./syntax/term.md). + +#### 2.12.0 + +- Functionality to [set image size](./syntax/media.md) enabled by default. + +## August 2022 + +### yfm-transform + +#### 2.11.0 + + - Support for inline formatting in the title of cuts and notes. + +#### 2.10.0 + +- Added the `needFlatListHeadings?: boolean;` parameter, which allows to form a flat list of all document headers in `transform().result.headings`. By default – `false`. + +## July 2022 + +### yfm-docs + +#### 1.23.0 + +- include/includers: allows 3rd party generated content integration into documentation. +- include/includers/sourcedocs: allows you to integrate sourcedocs generated document into yfm documentation. + [Includers](./project/toc.md#includers). + +## June 2022 + +### yfm-transform + +#### 2.9.0 + +- Added plugin for [file links](./syntax/links.md#files) + +#### 2.8.0 + +- Spaces inside inline conditions are not deleted. + +#### 2.7.0 + +- Single-page logic has been removed from the plugins (temporarily reverted in version 2.8.2). + +## May 2022 + +### yfm-transform + +#### 2.6.0 + +- Added plugin for [task lists syntax](./syntax/additional.md#tasks-list). + +## April 2022 + +### yfm-docs + +#### 1.22.0 + +- Support filtering of the title and title of the meta on the leading page (index.yaml). +- Support filtering of the title on the contents (toc.yaml). + +#### 1.21.0 + +- Supported using of symlinks with a relative path. + +## March 2022 + +### yfm-docs + +#### 1.20.0 + +- Supported filtering of the description on the leading page (index.yaml). + +#### 1.19.0 + +- The linter runs in parallel with the build +- The arguments `--link-disabled`, `--build-disabled` and `--add-map-file` are supported, by default they have the value `false`. + [Read more](tools/docs/settings.md) + +### yfm-transform + +#### 2.5.0 + +- Rewritten in Typescript. + +## December 2021 + +### yfm-docs + +#### 1.18.0 + +Update YFM to v2.4. Added support [monospaced text](./syntax/base.md) and [multiline tables](./syntax/tables/multiline.md). + +#### 1.17.0 + +* After pre-processing the documentation (with output-format=md), we do not remove not_var from the syntax similar to variables. + [Substitutions](./syntax/vars.md#subtitudes) + +#### 1.16.0 + +* Added modes for including toc: `root_merge`, `merge`, `link`. [Read more](./project/toc.md#include-mode). + +* If the toc includes another one under the `root_merge` and `merge` modes, the original path will be added + to the `sourcePath` meta field. + +### yfm-transform + +#### 2.4.0 + +* [Multiline tables](./syntax/tables/multiline.md) enabled by default. + +#### 2.3.0 + +* Added support [monospaced text](./syntax/base.md). + +## November 2021 + +### yfm-docs + +#### 1.15.0 + +* Added the ability to include `toc.yaml` with the addition of its elements to the same table of contents level. + + [Read more](./project/toc.md#include-as-pages) + +#### 1.14.0 + +* Added the ability to [configure the linter](./project/lint.md). + +### yfm-transform + +#### 2.2.0 + +* Added the ability to redefine delimiters in the plugin [markdown-it-attrs](https://www.npmjs.com/package/markdown-it-attrs). + +## October 2021 + +### yfm-transform + +#### 2.1.0 + +* Added beta-plugin for support multiline tables. + +## September 2021 + +### yfm-docs + +#### 1.13.0 + +* YFM2 is used. + +### yfm-transform + +#### 2.0 + +* YFM can be used on the client. +* The plug-in connection scheme has been changed. +* The [markdown-it-attrs](https://www.npmjs.com/package/markdown-it-attrs) plugin is always connected. +* The [highlight.js](https://www.npmjs.com/package/highlight.js) package must be installed independently. + +## July 2021 + +### yfm-docs + +#### 1.12.0 + +* The experimental YFM linter was disabled. + +### yfm-transform + +#### 1.9.0 + +* Added the ability to enable support for GitHub compatible anchors (GFM). + +## June 2021 + +### yfm-docs + +#### 1.11.0 + +* An experimental YFM linter was enabled. + +#### 1.10.0 + +* Now you can configure redirects using a special file. Static builds are not supported. + +#### 1.9.0 + +* Added support for sections accessible only by direct link. + +### yfm-transform + +#### 1.8.0 + +* Added experimental linter support. + +## April 2021 + +### yfm-docs + +#### 1.8.0 + +* Added the option to add file contributors to metadata. Only GitHub is supported out-of-the-box. It isn't displayed visually in any way, but can be used by a custom viewer. + +## March 2021 + +### yfm-docs + +#### 1.7.0 + +* Added complete disabling of variables: conditions are not calculated and values are not substituted. + +### yfm-transform + +#### 1.7.0 + +* Added complete disabling of variables: conditions are not calculated and values are not substituted. + +## January 2021 + +### yfm-docs + +#### 1.6.0 + +* Now you can build a document as a single HTML file. + +#### 1.5.0 + +* Refactoring and bug fixes. + +#### 1.4.0 + +* Added disabling the calculation of conditions with variables. + +### yfm-transform + +#### 1.6.0 + +* Added support for loops, filters, and functions. + +#### 1.5.0 + +* Added a feature to use the `not_var` flag for variables that don't need to be substituted with values. For example, `not_var{{ variable_name }}`. + +## October 2020 + +### yfm-docs + +#### 1.3.0 + +* Added the ability to display built files on S3. + +## August 2020 + +### yfm-docs + +#### 1.2.0 + +* Now the documentation interface allows the user to change the font size, turn on the dark theme, and hide the table of contents. + +### yfm-transform + +#### 1.4.0 + +* Added an option to use '|' in variables. + +## July 2020 + +### yfm-transform + +#### 1.3.0 + +* Basic element styles have been updated. + +#### 1.2.0 + +* Added support for inserting videos. + +#### 1.1.0 + +* Added support for multiple custom anchors per header. + +## June 2020 + +### yfm-docs + +#### 1.1.0 + +* Added silent mode without outputting build logs. diff --git a/en/contribution.md b/en/contribution.md new file mode 100644 index 00000000..94e96871 --- /dev/null +++ b/en/contribution.md @@ -0,0 +1,12 @@ +# Making edits + +The source files of this document and Diplodoc Platform tools are stored in repositories: + +* [Documentation](https://github.com/diplodoc-platform/docs) +* [Diplodoc](https://github.com/diplodoc-platform/diplodoc) +* + +You can submit bugs and suggestions as GitHub issues in the corresponding repository. + +To make edits, create a pull request from your fork. Edits will be reviewed by the repository owner. + diff --git a/en/how-it-work.md b/en/how-it-work.md new file mode 100644 index 00000000..df081871 --- /dev/null +++ b/en/how-it-work.md @@ -0,0 +1,74 @@ +# Main scenarios for Diplodoc usage +## Simple documentation project with YFM + + +### Project Structure +Basic project contains few config files and pages with actual content. Both config files and markdown linked into the following structure: + + +``` +input-folder +|-- .yfm (config file for whole project) +|-- toc.yaml (table of content) +|-- presets.yaml (presets for vairables) +|-- index.yaml (index page) +|-- pages (Content pages) + |-- faq.md + |-- how-to.md +|-- _assets (directory with pictures) + |-- image1.png + |-- image2.png +|-- _includes (directory for reusable content) + |-- faq_shared_block.md +``` + + +More information about the structure can be found on [the page](./project/index.md). + + + +### Project Build +Build can be performed with "Builder" tool with cli. + +For build initiation run the following with **mandatory** keys: + +- input, -i — path to project directory. + + +- output, -o —path to directory with output data (static HTML pages) + + +#### Example +``` +yfm -i ./input-folder -o ./ouput-folder +``` + + +### Result +After successful build you get either HTML-linked project or YFM. +YFM can be used for subsection creation. + + +### Usage +HTML-linked and ready project can be used locally, hosted on your favorite provider or placed into S3-like storage for further processing. + + + +## Integration into Development pipeline +### Project creation and build + +For common scenarios project structure and build procedures are the same as mentioned in previous section. +But in case of integration with your CI/CD pipelines it's required to include Builder for triggers on documentation updates in repository. + + + +### Plugins and extended configuration +Huge documentation projects are using extra capabilities for content processing and specific configurations for build. As an example - you can use plugins for complex tables of work with video. More details can be found on [the page](./plugins/index.md). + + + +## Work with GitHub and publication on your own domain or on https://diplodoc.com + +If you are using GitHub as your VCS and repository for your documentation - Diplodoc can be used for full pipeline creation, starting from making changes in .md files to hosting pf your project. + +[Contact us](https://diplodoc.com/#contact), to discuss details of your configuration. \ No newline at end of file diff --git a/en/index-yfm.md b/en/index-yfm.md new file mode 100644 index 00000000..7d46f770 --- /dev/null +++ b/en/index-yfm.md @@ -0,0 +1,60 @@ + +# Yandex Flavored Markdown +**Yandex Flavored Markdown (YFM)** is a Markdown dialect and a set of tools for [transforming](./tools/transform/index.md) Markdown to HTML in real time and [building](./tools/docs/index.md) complete documentation projects. + +* Corresponds to [CommonMark Spec](https://spec.commonmark.org/). +* Includes its own [set of plugins](./plugins/index.md) with additional features and markup elements. +* [Fast](https://www.npmjs.com/package/markdown-it#benchmark). +* Expandable: you can [add](./plugins/import.md) any plugin for markdown-it or [write your own](https://github.com/markdown-it/markdown-it/tree/master/docs). +* Safe: HTML is escaped by default. +* Uses dynamic validation. +* Allows you to build a documentation project. + +## Syntax {#syntax} + +The Yandex Flavored Markdown syntax is based on [CommonMark Spec](https://spec.commonmark.org/) and has been supplemented with unique elements from other markup languages and template engines. + +In particular: + +* [Notes](./syntax/notes.md) +* [Cuts and tabs](./syntax/cuts-tabs.md) +* [Video](./syntax/media.md#video) +* [Variables](./syntax/vars.md) +* [Reusable content](./project/includes.md) + +For more information about all markup elements, see [Syntax](./syntax/index.md). + +## Creating documentation projects {#project} + +[Builder](./tools/docs/index.md) allows you to build a complete documentation project: with navigation, internal links, and full support for Yandex Flavored Markdown. + +A built project is a set of static HTML files that can be viewed locally or on a host, in GitHub Pages, or in [S3](./tools/docs/publish-s3.md). It may include: + +* [Table of contents](./project/toc.md). + +* [Leading pages](./project/leading-page.md) for quick navigation. + +* [Variable presets](./project/presets.md) to support multiple versions of documentation from the same source files. + +* [Reusable content](./project/includes.md). + +* Custom display settings: + * Wide format. + * Current article navigation. + * Dark theme. + * Text size. + + You can try changing the settings right now: click ![settings-icon](./_images/user-settings.png) in the upper-right corner. + +In addition to building all files in HTML, you can build to a [single-page](./tools/docs/singlepage.md) and in [YFM](./tools/docs/build.md#yfm). + +## Under development {#future-releases} + +Future YFM releases are expected to include the following features: + +* Static linter. +* YFM generators from proto, OpenAPI, auto-generated Java, Python, C++, and Go documentation. +* Customer satisfaction score (CSAT) on documentation pages. +* Automatic local rebuild when changes are made. +* Displaying contributors on pages. +* Free hosting for open-source documentation projects. diff --git a/en/index.yaml b/en/index.yaml new file mode 100644 index 00000000..3194eb28 --- /dev/null +++ b/en/index.yaml @@ -0,0 +1,18 @@ +title: Diplodoc +description: Diplodoc Platform is open platform for work with your documentation in accordance with "Documentation as a Code" paradigm. +meta: + title: Metadata + noIndex: true +links: +- title: Overview + description: Platform Overview, Capabilities and Benefits. + href: about.md +- title: Quick Start + description: How to start + href: how-it-work.md +- title: Yandex Flavored Markdown + description: Definition for Yandex Flavored Markdown. + href: index-yfm.md + + + diff --git a/en/plugins/import.md b/en/plugins/import.md new file mode 100644 index 00000000..47143585 --- /dev/null +++ b/en/plugins/import.md @@ -0,0 +1,64 @@ +# Adding additional plugins + +YFM uses [markdown-it](https://www.npmjs.com/package/markdown-it) as a parser, so you can add any plugin from the [markdown-it plugin list](https://www.npmjs.com/search?q=keywords:markdown-it-plugin). + +## Adding plugins {#require} + +Before adding a plugin, install the package that contains it using the `npm i ` command. For example, to install [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji), run: + +```shell +npm i markdown-it-emoji +``` + +{% list tabs %} + +- Transformer + + 1. Add the plugin in your code using the `require()` or `import()` function: + + ```javascript + const plugin1 = require(''); + ``` + + 1. For the `plugins` parameter, add a new plugin to the array: + + ```javascript + const {result: {html, meta}, logs} = transform(content, {plugins: []}); + ``` + + **Example:** + + ```javascript + const fs = require('fs'); + const transform = require('@doc-tools/transform'); + const cut = require('@doc-tools/transform/lib/plugins/cut'); + const sup = require('@doc-tools/transform/lib/plugins/sup'); + const emoji = require('markdown-it-emoji'); + const content = fs.readFileSync(filePath, 'utf'); + const {result: {html, meta}, logs} = transform(content, {plugins: [cut, sup, emoji]}); + ``` + + {% note warning %} + + When overriding the `plugins` parameter, you must reconnect [YFM plugins](index.md). To do this, import them from the `@doc-tools/transform` package and pass them in the plugin array. + + {% endnote %} + +- Builder + 1. Move the installed plugin to the `./plugins` folder in the `@doc-tools/docs` package. + + {% note tip %} + + If you don't want to transfer the necessary plugins before each build, build your own Builder: + * Install the source code with [GitHub](https://github.com/yandex-cloud/yfm-docs). + * Move the additional plugins to the `./plugins` folder. + * Build the Builder by following the [GitHub instructions](https://github.com/yandex-cloud/yfm-docs#installation-1). + + {% endnote %} + +{% endlist %} + +## Passing parameters {#options} + +YFM applies unknown parameters from the `options` object to all plugins, so to pass parameters, add them to the `options` object. + diff --git a/en/plugins/index.md b/en/plugins/index.md new file mode 100644 index 00000000..db3bd41d --- /dev/null +++ b/en/plugins/index.md @@ -0,0 +1,14 @@ +# Plugins + +Besides the basic [CommonMark Spec](https://spec.commonmark.org/) syntax, YFM provides a set of plugins with additional features and unique markup elements. + +{% note warning %} + +The order of plugins is important. When adding plugins, you should specify the full set of plugins + +{% endnote %} + +{% include [plugins.md](../_includes/plugins.md) %} + +The plugins included in the YFM package are listed above. You can also [add additional](import.md) plugins or write your own using the [markdown-it guidelines](https://github.com/markdown-it/markdown-it/tree/master/docs). + diff --git a/en/project/config.md b/en/project/config.md new file mode 100644 index 00000000..d99fadf8 --- /dev/null +++ b/en/project/config.md @@ -0,0 +1,22 @@ +# Configuration file + +In the configuration file, you can specify: + +* [Standard YFM settings](../settings.md). +* [YFM to HTML transformation settings](../tools/transform/settings.md). +* [Build settings](../tools/docs/settings.md). + +By default, the `.yfm` file is located at the root of the document. When building, you can specify the path to another file using the [launch key](../tools/docs/settings.md) `--config`. + +## Structure + +The `.yfm` configuration file contains a list of all parameters in YAML format: + +```yaml +parameter: value +parameter: value +``` + +* `parameter`: Name of the setting. +* `value`: Setting value. + diff --git a/en/project/includes.md b/en/project/includes.md new file mode 100644 index 00000000..3da9cc33 --- /dev/null +++ b/en/project/includes.md @@ -0,0 +1,34 @@ +# Reusing content + +You can put recurring content in a separate file and add it to the necessary places in the document using the construction `{% include %}`. + +Reusing content helps reduce the time spent on editing and searching the source text: information is stored in one place, and changes are automatically applied to all files. + +## Instructions for reusing content {#steps} + +1. Create a folder to store recurring content. For example, `_includes`. + + {% note warning %} + + Images should be stored in a folder whose name starts with `_`. Otherwise, they will be deleted during the build. + + {% endnote %} + +1. In the `_includes` folder, create a separate MD file with the recurring text. + +1. In sections of a document where you need to insert this text, add a link to the file in the following format: + + ```markdown + {% include [Description](../_includes/file.md) %} + ``` + * `[Description]`: File description. Information about document authors does not affect the build. + * `(_includes/file.md)`: File path. + + If you don't need to add the header of the reusable file to the section, add the `notitle` keyword: + + ```markdown + {% include notitle [Description](../_includes/file.md) %} + ``` + +When building the document, the text of the file is added to the sections in place of the includes. If there are relative links in the file, they are re-assembled. + diff --git a/en/project/index.md b/en/project/index.md new file mode 100644 index 00000000..c32d0c38 --- /dev/null +++ b/en/project/index.md @@ -0,0 +1,35 @@ +# Documentation project + +YFM supports creating and maintaining documentation projects of any size. + +**Example**: [Yandex.Cloud documentation](https://github.com/yandex-cloud/docs). + +## Project structure + +In the most basic case, a project consists of a [table of contents file](./toc.md) and files with content. + +To optimize the documenting process and improve the appearance of pages, you can additionally include: + +* [A leading page](./leading-page.md) for quick navigation. +* [Variable presets](./presets.md) to support multiple versions of documentation from the same source files. +* [A configuration file](./config.md) with project settings. +* Folders for [reusing content](./includes.md) and storing [images](../syntax/media.md#images). + +## Example + +``` +input-folder +|-- .yfm (Configuration file) +|-- toc.yaml (Table of contents) +|-- presets.yaml (Variable presets) +|-- index.yaml (Leading page) +|-- pages (Content files) + |-- faq.md + |-- how-to.md +|-- _assets (Folder with images) + |-- image1.png + |-- image2.png +|--_includes (Folder with files to be reused) + |-- faq_shared_block.md +``` + diff --git a/en/project/leading-page.md b/en/project/leading-page.md new file mode 100644 index 00000000..8f94f86b --- /dev/null +++ b/en/project/leading-page.md @@ -0,0 +1,62 @@ +# Leading page + +To quickly navigate the document, you can design a root page in the form of a grid with links to main sections. + +**Example**: design of the [Yandex Compute Cloud documentation](https://cloud.yandex.com/docs/compute/) leading page. + +![Example of a leading page](../_images/leading.jpg) + +## Structure {#structure} + +The standard file structure of the `index.yaml` leading page: + +```yaml +title: Document name +description: A description of the document +meta: + title: Metadata + noIndex: true +links: +- title: First section + description: A description of the first section + href: path/to/file.md +- title: Second section + description: A description of the second section + href: path/to/file.md +``` + +* `title`: Document name. It's displayed in the table of contents above the list of all sections. +* `description`: A description of the document. +* `meta`: [Metadata](../syntax/meta.md#meta). +* `links`: Grouping element. The following is set within each section: + * `title`: Name of the section. Displayed as the name of the link. + * `description`: Description of the section. + * `href`: The relative path to the file. + +## Element visibility conditions {#when} + +Individual sections can be included on or excluded from a leading page, depending on the values of [variables](../syntax/vars.md). To describe visibility conditions, the `when` parameter is used. + +Possible comparison operators: `==`, `!=`, `<`, `>`, `<=`, and `>=`. + +```yaml +- title: Section with a conditional inclusion. + description: A description of the section. + href: path/to/conditional/file.md + when: version == 12 +``` + +## Substitutions and conditional operators {#subtitudes} + +Title and description of document and links support [substitutions](../syntax/vars#subtitudes) and [conditional operators](../syntax/vars#conditions). + +```yaml +title: "{{ title }}" +description: "{% if version == 10 %}{{ description_legacy }}{% else %}{{ description }}{% endif %}" +meta: + title: "{{ meta_title }}" +links: +- title: "{{ link_title }}" + description: "{{ link_description }}" + href: path/to/conditional/file.md +``` diff --git a/en/project/lint.md b/en/project/lint.md new file mode 100644 index 00000000..1267566b --- /dev/null +++ b/en/project/lint.md @@ -0,0 +1,96 @@ +# Linter configuration file + +A project may contain a linter configuration file. By default, a `.yfmlint` file is used in the root of the project. + +The default config looks like this: + +```yaml +log-levels: + MD001: 'disabled' # Heading levels should only increment by one level at a time + MD002: 'disabled' # First heading should be a top-level heading~~ + MD003: 'disabled' # Heading style + MD004: 'disabled' # Unordered list style + MD005: 'disabled' # Inconsistent indentation for list items at the same level + MD006: 'disabled' # Consider starting bulleted lists at the beginning of the line~~ + MD007: 'disabled' # Unordered list indentation + MD009: 'disabled' # Trailing spaces + MD010: 'disabled' # Hard tabs + MD011: 'disabled' # Reversed link syntax + MD012: 'disabled' # Multiple consecutive blank lines + MD013: 'disabled' # Line length + MD014: 'disabled' # Dollar signs used before commands without showing output + MD018: 'error' # No space after hash on atx style heading + MD019: 'disabled' # Multiple spaces after hash on atx style heading + MD020: 'disabled' # No space inside hashes on closed atx style heading + MD021: 'disabled' # Multiple spaces inside hashes on closed atx style heading + MD022: 'disabled' # Headings should be surrounded by blank lines + MD023: 'disabled' # Headings must start at the beginning of the line + MD024: 'disabled' # Multiple headings with the same content + MD025: 'disabled' # Multiple top-level headings in the same document + MD026: 'disabled' # Trailing punctuation in heading + MD027: 'disabled' # Multiple spaces after blockquote symbol + MD028: 'disabled' # Blank line inside blockquote + MD029: 'disabled' # Ordered list item prefix + MD030: 'disabled' # Spaces after list markers + MD031: 'disabled' # Fenced code blocks should be surrounded by blank lines + MD032: 'disabled' # Lists should be surrounded by blank lines + MD033: 'disabled' # Inline HTML + MD034: 'disabled' # Bare URL used + MD035: 'disabled' # Horizontal rule style + MD036: 'disabled' # Emphasis used instead of a heading + MD037: 'disabled' # Spaces inside emphasis markers + MD038: 'disabled' # Spaces inside code span elements + MD039: 'disabled' # Spaces inside link text + MD040: 'disabled' # Fenced code blocks should have a language specified + MD041: 'disabled' # First line in a file should be a top-level heading + MD042: 'disabled' # No empty links + MD043: 'disabled' # Required heading structure + MD044: 'disabled' # Proper names should have the correct capitalization + MD045: 'disabled' # Images should have alternate text (alt text) + MD046: 'disabled' # Code block style + MD047: 'disabled' # Files should end with a single newline character + MD048: 'disabled' # Code fence style + + YFM001: 'warn' # Inline code length + YFM002: 'warn' # No header found in the file for the link text + YFM003: 'error' # Link is unreachable + +# Inline code length +YFM001: + maximum: 100 +``` + +Rules with the prefix `MD` are provided by the library [markdownlint](https://github.com/DavidAnson/markdownlint). +A detailed description of all the rules with `MD` prefix can be found [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). +A detailed description of all the rules with `YFM` prefix can be found [here](https://github.com/yandex-cloud/yfm-transform/blob/master/lib/yfmlint/README.md). + +In the `.yfmlint` config in the `log-levels` section, you can override the logging level separately for each rule: `error`, `warn`, `disabled`. + +In the root section of the config, you can configure the values passed to the rules. For example: + +```yaml +# Inline code length +YFM001: + maximum: 100 + +# Line length +MD013: + line_length: 100 # default: 80 characters + code_blocks: false # exclude this rule for code_blocks + tables: fales # exclude this rule for tables + headings: false # exclude this rule for headings + +# Inline HTML +MD033: + allowed_elements: [ "span", "br", "p" ] + + +# Section for defining log levels +log-levels: +``` + +Default values for rules with the prefix `MD` are specified [here.](https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml) +Default values for rules with the prefix `YFM` are specified [here.](https://github.com/yandex-cloud/yfm-transform/blob/master/lib/yfmlint/yfmlint.js) + +Rules can be enabled, disabled, and configured for an entire file or a paragraph of a file. +Look at the examples [here.](https://github.com/DavidAnson/markdownlint/blob/a852407c887ec60949aa5365ed964bab833f962f/README.md#configuration) diff --git a/en/project/presets.md b/en/project/presets.md new file mode 100644 index 00000000..d8821067 --- /dev/null +++ b/en/project/presets.md @@ -0,0 +1,52 @@ +# Variable presets + +Presets are groups of [variables](../syntax/vars.md) with different values. + +Presets are used to support multiple documentation versions from the same source files. For example, if the documentation contains internal information, you can create two presets: `internal` and `external`, and you won't need to store the variable values in the build files. + +How to work with presets: + +1. Describe the presets in `presets.yaml`. +1. When [building](../tools/docs/index.md), specify the name of the preset used in the `varsPreset` parameter. + +## Structure {#structure} + +The `presets.yaml` file should contain a `default` preset. When calculating variables, the values specified in `default` are taken into account first. Then the values from the preset passed at the start of the build override them, since it takes priority. + +```yaml +default: + position: The Wizard +internal: + place: Emerald City +external: + place: The Land of Oz +``` + +## Hierarchy of preset files {#hierarchy } + +You can use multiple preset files. When calculating variables, the ones that are closer to the converted file will have higher priority. + +{% note tip %} + +We recommend using top-level presets: the ones closest to the root of the project. + +{% endnote %} + +#### Example + +``` +input-folder +|-- .yfm +|-- toc.yaml +|-- presets.yaml // 2 +|-- index.yaml +|-- quickstart.md +|-- pages + |-- presets.yaml // 1 + |-- faq.md + |-- how-to.md +``` + +* When building a file named `faq.md`, the variable values declared in file 1 take priority over file 2. +* When building `quickstart.md`, only the variable values declared in file 2 are taken into account. + diff --git a/en/project/toc.md b/en/project/toc.md new file mode 100644 index 00000000..0b8e7d46 --- /dev/null +++ b/en/project/toc.md @@ -0,0 +1,405 @@ +# Table of contents + +The document structure is described in the file `toc.yaml`. It defines how a table of contents is generated and documentation is built. + +{% note warning %} + +Files that are not specified in `toc.yaml` are not processed during the build. + +{% endnote %} + +## Structure {#structure} + +The standard `toc.yaml` file structure looks like the following: + +```yaml +title: Document title +href: index.yaml +items: + - name: Section name + href: path/to/file.md + - name: Section group name + items: + - name: Section name + href: path/to/file.md + - name: Section name + href: path/to/file.md + - name: Section name + href: path/to/file.md +``` + +* `title`: Document name. It's displayed in the table of contents above the list of all sections. +* `name`: The name of a section or group of sections. +* `href`: A relative path to the file. +* `items`: A grouping element. + +## Section visibility conditions {#when} + +Individual sections can be included in or excluded from the document, depending on the values of [variables](../syntax/vars.md). To describe visibility conditions, the `when` parameter is used. + +Possible comparison operators: `==`, `!=`, `<`, `>`, `<=`, `>=`. + +```yaml +- name: Section with conditional entry + href: path/to/conditional/file.md + when: version == 12 +``` + +## Substitutions and conditional operators {#subtitudes} + +Document title supports [substitutions](../syntax/vars#subtitudes) and [conditional operators](../syntax/vars#conditions). + +```yaml +title: "{{ title }}" +``` + +{% note warning %} + +Always use quotes if a value starts with a substitution. Without quotes, the value is processed as JSON embedded in YAML, which can lead to build errors such as `TypeError: str.replace is not a function`. + +{% endnote %} + +## Inserting tables of contents {#includes} + +You can split a table of contents into different files and insert one table of contents into another. Use cases: +* You have table of contents blocks in several documents. +* You have a large document, which is easier to build from smaller blocks. + +### Example of including a table of contents as a section {#include-as-section} + +```yaml +- name: Imported block name + include: + path: another/toc.yaml +``` + +By default, `path` specifies the path from the documentation root. The name of the imported file doesn't have to be `toc.yaml`: + +```yaml +- name: Instructions for Android + include: + path: another/toc_android.yaml +``` + +### Example of including a table of contents without creating a section {#include-as-pages} + +You can also include `toc.yaml` with its elements in the same level of the table of contents. + +`toc.yaml`: + +```yaml +items: + - name: Name1 + href: file1.md + + # If an element doesn't have a name field, it means that elements of the included table of contents must be + # added to the same table of contents level, not as a new section + - include: { path: path/to/toc.yaml } + + - name: NameX + href: fileX.md +``` +`path/to/toc.yaml`: + +```yaml +items: + - name: NameA + href: fileA.md + - name: NameB + href: fileB.md +``` +Result in the table of contents: +- Name1 +- NameA +- NameB +- NameX + + +### mode {#include-mode} + +Different modes that can be set in the `mode` property: + +* `root_merge`: Enabled by default. This copies the table of contents along with all of the files and directories it uses. Let's say that you're importing the contents from folder A into the contents in folder B. All of the files from folder A will be copied to folder B during the build. Note that copying overwrites files. + + The copying process changes the project structure, and `sourcePath` is added to the new files' metadata with the path to the source file. This field is used for the link to edit the page. +* `merge`: Similar to `root_merge`, but the path to the table of contents file is specified relative to the current file where you are using `include`. +* `link`: The project structure doesn't change. All of the included table of contents' links are changed to links relative to the table of contents where it's included. + +For example, let's say you want to specify a relative path in `path` to the table of contents you are importing. Do it like this: + +```yaml +items: + - include: { mode: merge, path: ../relative/path/to/toc.yaml } +``` + +### Includers {#includers} + +You can include any content using `includers`, as long as the includer for this type of content is implemented. + +Includers are specified as: + +- an array of `includer` objects in the `includers` field + +- `includer` object in the `includer` field. _in the process of deprecation in favor of the `includers` field_ + +{% note warning "include requirements" %} + +`include` should provide `path` where content is gonna be included + +`path` field must be the **path to where content is gonna be included**. + +`mode` must be **link or omitted** + +{% endnote %} + +{% note warning "includers requirements" %} + +`includers` must be array of includer objects that are going to be executed +in the order they were provided + +{% endnote %} + +{% note warning "includer requirements" %} + +parameters between includer objects differ but one common parameter is the **name of the includer to execute** + +`name` specify name of the includer to run + +{% endnote %} + +#### Usage example + +abstract example of the includers usage + +_refer to appropriate includer section for the concrete usage example_ + +``` +# toc.yaml +... +items: + - name: + include: + path: + includers: + - name: + : + - name: + - name: + mode: link +... +``` + +#### List of implemented includers + +- [Generic](#includers-generic) +- [Open API](#includers-open-api) +- [Unarchive](#includers-unarchive) +- [Source Docs](#includers-source-docs) _in the process of deprecation in favor of generic includer_ + +#### Generic {#includers-generic} + +You can generate documentation in the **markdown format** with **the tool of your choice** and include it into your main documentation. + +Includer will generate table of content for the provided content and include it as it is. + +##### Usage example + +Let's say we have a documentation project in the `doc_root` folder. + +Put markdown content generated with the tool of your choice inside `doc_root/docs` folder. + +Then you need to include it inside `doc_root/toc.yaml` with generic `includer`. + +Link to the generated leading page inside main `doc_root/index.yaml`. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: docs + include: + path: docs + includers: + - name: generic + input: docs + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: docs + href: docs/ +``` + +#### Open API {#includers-open-api} +You can generate documentation from the [Open API](https://www.openapis.org/) specification file and include it into your main document. + +{% note warning %} + +openapi includer requires you to enable usage of HTML inside documentation + +set `allowHTML` to `true` inside `.yfm` config + +``` +allowHTML: true +``` + +{% endnote %} + +##### Usage example + +Let's say we have a documentation project in the `doc_root` folder. + +Put specification file into it at `doc_root/openapi.yaml`. + +Then you need to include it inside `doc_root/toc.yaml` with the openapi `includer` + +Link to the generated leading page inside main `doc_root/index.yaml` + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: openapi + include: + path: openapi + includers: + - name: openapi + input: openapi.yaml + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: openapi + href: openapi/ +``` + +#### Unarchive {#includers-unarchive} + +You can use `unarchive` includer to unpack your tarball before applying other includers e.g `generic` includer. + +##### Usage example + +As an example you might have `docs.tar` inside root of your documentation project `doc_root/docs.tar`. + +`docs.tar` has markdown content inside of it, that you would like to include with `generic` includer. + +Then you would apply chain of the includers(`unarchive` -> `generic`) to achive desired results. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: +... + - name: multiple + include: + path: multiple + mode: link + includers: + # run unarchive includer + - name: unarchive + # specify tarball you want to unpack as input parameter + input: docs.tar + # specify output path where tarball content is going to be unpacked + output: unpacked + # run generic includer + - name: generic + # specify path from unarchive includers output field as input path + input: unpacked +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: openapi + href: openapi/ +``` + +#### Source Docs {#includers-source-docs} + +You can generate documentation with [Source Docs](https://github.com/SourceDocs/SourceDocs) and include it into your main documentation. + +{% note warning %} + +Source Docs includer is getting depricated in the favor of [Generic Includer](#includers-generic) + +{% endnote %} + +##### Usage example + +Let's say we have a documentation project in the `doc_root` folder. + +Put the output of the Source Docs into the `doc_root/docs` folder. + +Then you need to include it inside `doc_root/toc.yaml` with sourcedocs `includer`. + +Link to the generated leading page inside main `doc_root/index.yaml`. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: docs + include: + path: docs + includers: + - name: sourcedocs + input: docs + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: docs + href: docs/ +``` + +## Section expansion { #expanded } + +By default, all table of contents sections are hidden. You can change it by adding `expanded`: + +```yaml +title: Yandex Cloud Marketplace +items: + - name: Getting started + href: index.md + - name: Test topichead + expanded: true + items: + - name: Creating a virtual machine + href: create.md + - name: Initial software configuration + href: setup.md + - name: Operating a virtual machine + href: operate.md + - name: API reference + href: guide.md +``` + +You can only use `expanded` for first-level sections. In lower sections, `expanded` will be ignored. +Use it to make important sections and pages in the table of contents always visible. + + +## Hidden sections {#hidden} + +To make a section accessible only by direct link and excluded it from the table of contents, add the `hidden` parameter. + +```yaml +- title: Secret document + href: secret.md + hidden: true +``` + +To completely exclude hidden sections from the build, use the [build key](../tools/docs/settings.md) `--remove-hidden-toc-items=true`. diff --git a/en/settings.md b/en/settings.md new file mode 100644 index 00000000..0d423e28 --- /dev/null +++ b/en/settings.md @@ -0,0 +1,21 @@ +# Settings + +Standard YFM settings are listed below. Depending on the tool you use, you can configure them in one of the following ways: + +* In a [configuration file](./project/config.md). +* As a function parameter ([Transformer](./tools/transform/settings.md)). +* Via startup keys ([Builder](./tools/docs/settings.md)). + +| Name | Description | Type | Default value | +| :--- | :--- | :--- | :--- | +| `vars` | [Variables](./syntax/vars.md) | `Object` | `{}` | +| `allowHTML` | Allow HTML in markup | `bool` | `false` | +| `linkify` | Convert link-like strings to links | `bool` | `false` | +| `breaks` | Use the carriage return character for a line break | `bool` | `true` | +| `conditionsInCode` | Meet conditions in code blocks | `bool` | `false` | +| `disableLiquid` | Disable the use of variables | `bool` | `false` | +| `supportGithubAnchors` | Generate additional [anchors](./syntax/base.md#headers) that are compatible with GitHub | `bool` | `false` | +| `lang` | Localization language of default texts | `string` | `ru` | +`needToSanitizeHtml` | Need to sanitize the generated HTML | `bool` | `false` +`sanitizeOptions` | Sanitizer configuration | `Object` | `undefined` +`linkifyTlds` | Allow set tld for the linkify plugin | `string \| string[]` | `undefined` diff --git a/en/syntax/additional.md b/en/syntax/additional.md new file mode 100644 index 00000000..75b71485 --- /dev/null +++ b/en/syntax/additional.md @@ -0,0 +1,75 @@ +# Additional features + +The following markup elements are not supported by default, but can be added using [markdown-it plugins](https://www.npmjs.com/search?q=keywords:markdown-it-plugin). + +For more information about how to add additional plugins, see the [instructions](../plugins/import.md). + +## Subscript {#sub} + +**Plugin:** [markdown-it-sub](https://www.npmjs.com/package/markdown-it-sub) + +To output a character in subscript, add `~` on both sides. + +```markdown +H~2~O +``` + +You can vote to include subscript support in YFM by default in [GitHub issues](https://github.com/yandex-cloud/yfm-transform/issues/70). + +## Underlined text {#underline} + +**Plugin:** [markdown-it-ins](https://www.npmjs.com/package/markdown-it-ins) + +To underline text, add `++` on both sides. + +```markdown +++qwerty++ +``` + +You can vote to include underlined text support in YFM by default in [GitHub issues](https://github.com/yandex-cloud/yfm-transform/issues/71). + +## Footnotes {#footnotes} + +**Plugin:** [markdown-it-footnote](https://www.npmjs.com/package/markdown-it-footnote) + +Use footnotes for additional information without complicating the text. Footnotes have two parts connected with tags: + +* The link in the document text, which is displayed as superscript. +* A block of additional information. It's usually placed at the end of the document. + +```markdown +Here's a simple footnote,[^1] and here's a longer one.[^bignote] + +[^1]: This is the first footnote. + +[^bignote]: Here's one with multiple paragraphs and code. +``` + +You can vote to include footnote support in YFM by default in [GitHub issues](https://github.com/yandex-cloud/yfm-transform/issues/72). + +## Task lists {#tasks-list} + +Import plugin from package like so: +``` +const checkbox = require('@doc-tools/transform/lib/plugins/checkbox'); +``` + +The task list is a list of checkboxes. A normal item is represented by the `- [ ]` symbol, a checked one by `- [x]`. You can use [line formatting](./base.md#line) in the task description. + +```markdown +- [x] ~~Write the press release~~ +- [ ] Update the website +- [ ] Contact the media +``` + +You can vote to include task list support in YFM by default in [GitHub issues](https://github.com/yandex-cloud/yfm-transform/issues/73). + +## Formulas {#formulas} + +**Plugin:** [markdown-it-katex](https://www.npmjs.com/package/markdown-it-katex) (see [other versions](https://www.npmjs.com/search?q=markdown-it-katex)) + +The plugin uses the KaTeX library to display mathematical symbols. Example of a formula: + +```markdown +$\sqrt{3x-1}+(1+x)^2$ +``` diff --git a/en/syntax/base.md b/en/syntax/base.md new file mode 100644 index 00000000..cc9e2183 --- /dev/null +++ b/en/syntax/base.md @@ -0,0 +1,113 @@ +# Basic markup + +## Line formatting {#line} + +Use the markup methods below to format a text fragment in a line. + +| Markup | Result | +|--------------------------| ----- | +| `**Bold text**` | **Bold text** | +| `_Italic_` | _Italic_ | +| `**_Bold italic_**` | **_Bold italic_** | +| `_**Also bold italic**_` | _**Also bold italic**_ | +| `~~Strikethrough text~~` | ~~Strikethrough text~~ | +| `Super^script^` | Super^script^ | +| `##Monospaced text##` | ##Monospaced text## + +To use subscript or underlined text, you need to add additional plugins. For more information, see [Additional features](./additional.md). + +## Headers {#headers} + +There are 4 levels of headers: + +* The first level (h1) is for the page header (title). +* The second (h2), third (h3), and fourth (h4) levels are for subsection headers. + +```markdown +# h1 header +## h2 header +### h3 header +#### h4 header +``` + +During the build, an anchor is created for each header. Anchors allow you to create [links](./links.md) to document sections. + +By default, the anchor in YFM is the header text written in Latin letters. You can set the anchor manually by specifying it after the header: + +```markdown +## h2 header {#anchor} +``` + +To simultaneously generate anchors following GitHub rules with the YFM anchors, in the [settings](../settings.md), set `supportGithubAnchors: true`. + +## Paragraphs {#sections} + +To create a paragraph, separate one block of text from another with an empty line. + +```markdown +Paragraph. + +Next paragraph. +``` + +**Result** + +Paragraph. + +Next paragraph. + +## Line breaks {#breaks} + +To move a line, move the carriage. + +```markdown +Line. +Next line. +``` + +**Result** + +Line. +Next line. + +To use two spaces at the end of the line instead of a carriage return, in the [settings](../settings.md), set `breaks: false`. + +## Quotes {#quotes} + +```markdown +> Quote +``` + +**Result** + +> Quote + +```markdown +> Quote +>> Nested quotes +``` + +**Result** + +> Quote + +>> Nested quotes + +## Escaping {#escaping} + +To prevent a markup syntax symbol from being interpreted, escape it with the `\` symbol. + +```markdown +Super^script^ +Super\^script^ +``` + +**Result** + +Super^script^ +Super\^script^ + +## Using HTML {#html} + +By default, YFM escapes HTML. To disable escaping, in the [settings](../settings.md), set `allowHTML: true`. + diff --git a/en/syntax/code.md b/en/syntax/code.md new file mode 100644 index 00000000..87a00aee --- /dev/null +++ b/en/syntax/code.md @@ -0,0 +1,34 @@ +# Code snippets + +You can add a code snippet to the text of a paragraph or make it a separate block. + +## In the text {#inline} + +To add a code snippet to the text, use the ` symbol. + +```markdown +`Code snippet` in the text. +``` + +**Result** + +`Code snippet` in the text. + +{% note tip %} + +We recommend using no more than 100 characters, because the text in these fragments doesn't wrap. For a larger number of characters, make the code a separate block. + +{% endnote %} + +## Separate block {#block} + +To make a code snippet a separate block, separate it from the rest of the text on both sides with the characters ```. + +To highlight the syntax, specify the language in which the code is written in the initial line. For example: + +```markdown +```sql +``` + +The list of available languages can be found on [Github](https://github.com/highlightjs/highlight.js/tree/master/src/languages). For information on how to transfer an additional set of languages, see [Connecting an additional language](../tools/transform/highlight.md#add). + diff --git a/en/syntax/cuts-tabs.md b/en/syntax/cuts-tabs.md new file mode 100644 index 00000000..6b0432e0 --- /dev/null +++ b/en/syntax/cuts-tabs.md @@ -0,0 +1,74 @@ +# Cuts and tabs + +With YFM extensions, you can use interactive markup elements: cuts and tabs. + +{% note info %} + +The content of cuts and tabs can include any YFM markup. + +{% endnote %} + +## Cuts {#cuts} + +Use cuts to hide content. For example, additional information or long blocks of code. + +```markdown +{% cut "Cut header" %} + +Content displayed when clicked. + +{% endcut %} +``` + +**Result** + +{% cut "Cut header" %} + +Content displayed when clicked. + +{% endcut %} + +## Tabs {#tabs} + +Use tabs for mutually exclusive sections. For example, to separate instructions for different operating systems. + +To display tabs correctly, separate them with empty lines: + +* `{% list tabs %}` and `{% endlist %}`. +* The text of one tab and the name of the next tab. + +```markdown +{% list tabs %} + +- The name of tab1 + + The text of tab1. + + * You can use lists. + * And **other** markup. + +- The name of tab2 + + The text of tab2. + +{% endlist %} +``` + +**Result** + +{% list tabs %} + +- Name of tab1 + + The text of tab1. + * You can use lists. + * And **other** markup. + +- Name of tab2 + + The text of tab2. + +{% endlist %} + +{% endcut %} + diff --git a/en/syntax/index.md b/en/syntax/index.md new file mode 100644 index 00000000..a978cf90 --- /dev/null +++ b/en/syntax/index.md @@ -0,0 +1,19 @@ +# Syntax + +The Yandex Flavored Markdown syntax is based on [CommonMark Spec](https://spec.commonmark.org/) and has been supplemented with unique elements from other markup languages and template engines. + +To format text, the following is used: + +* [Basic markup](./base.md) +* [Lists](./lists.md) +* [GFM](./tables/gfm.md) and [multiline tables](./tables/multiline.md) +* [Notes](./notes.md) +* [Cuts and tabs](./cuts-tabs.md) +* [Links](./links.md) +* [Media](./media.md) +* [Code snippets](./code.md) +* [Comments and metadata](./meta.md) +* [Variables](./vars.md) + +In addition to the items included in the package, [additional features](./additional.md) are available. They can be added using [plugins for markdown-it](https://www.npmjs.com/search?q=keywords:markdown-it-plugin). + diff --git a/en/syntax/links.md b/en/syntax/links.md new file mode 100644 index 00000000..0f659631 --- /dev/null +++ b/en/syntax/links.md @@ -0,0 +1,113 @@ +# Links + +The standard markup for a link is: + +``` +[link_text](link "hint_text") +``` + + * `link_text`: The link text. + * `link`: A URL or path to a file. + * `"hint_text"`: A hint that will be displayed when you hover over the link text. Optional. + +Depending on the type of link, simplifications and other design options are allowed. + +## Link to MD file {#autotitle} + +You can create a link to an MD file without explicitly specifying the link text. To do this, add the symbols `{#T}` in place of the text, and they will automatically be substituted with the title of the specified file. + +```markdown +[{#T}](./index.md) +``` + +**Result** + +[{#T}](./index.md) + + +## Link to MD file section {#auto-section-title} + +You can refere: + +* To the section of the current page. + + `[text](#anchor)` + + **Result** + + [{#T}](#formatting) + +* To a section of another page. + + `[text](base.md#anchor)` + + **Result** + + [{#T}](base.md#headers) + +## A URL or an email address {#url-email} + +To convert a URL or an email address to a link, add angle brackets `<>` on both sides. + +```markdown + + + +``` + +**Result** + + + + + +## Reference-style markup for links {#reference-style} + +Use reference-style links to make the source text of a document easier to read. These links consist of two parts connected by tags: + +* A brief link description in the text. + + `[link_text][link_tag]` + +* A long URL placed in a special place at the end of a paragraph or document. + + `[link_tag]: URL` + +```markdown +My favorite search engine is [Yandex][1]. + +[1]: https://yandex.com/ "The best search engine" +``` + +**Result** + +My favorite search engine is [Yandex][1]. + +[1]: https://yandex.com/ "The best search engine" +## Link text style {#formatting} + +You can apply [line formatting](./base.md#line) to the link text. + +```markdown +I love the **[Yandex Cloud](https://cloud.yandex.com)**. +This is the _[YFM Guide](https://yadocs.tech)_. +See the section on [`code`](#code). +Super [^men^](https://en.wikipedia.org/wiki/Major_Grom_(2017_film)). +``` + +**Result** + +I love **[Yandex.Cloud](https://cloud.yandex.com)**. +This is the _[YFM Guide](https://yadocs.tech)_. +See the section on [`code`](#code). +Super [^men^](https://en.wikipedia.org/wiki/Major_Grom_(2017_film)). + +## Files {#files} + +If you need to specify a link to a file, you can use a special link with a file icon. After clicking on such a link, the browser will start downloading the specified file to the device. + +```markdown +{% file src="data:text/plain;base64,Cg==" name="empty.txt" %} +``` + +{% file src="data:text/plain;base64,Cg==" name="empty.txt" %} diff --git a/en/syntax/lists.md b/en/syntax/lists.md new file mode 100644 index 00000000..cd69ab9b --- /dev/null +++ b/en/syntax/lists.md @@ -0,0 +1,128 @@ +# Lists + +The following types of lists are available: + +* Numbered: For describing a sequence of actions. +* Bulleted: For listing elements when the order isn't important. +* Definition: For creating glossaries. + +Each list type can contain any markup elements and nested items. + +## Numbered list {#numbered} + +To make a numbered list, use numbers with the `.` or `)` symbol. Numbering is performed dynamically during building, so the order of the numbers is not important. + +```markdown +1. First item. +1. Second item. +1. Third item. +``` + +**Result** + +1. First item. +1. Second item. +1. Third item. + +## Bulleted list {#marked} + +To make a bulleted list, use the `*`, `-`, or `+` symbols. + +For example: + +```markdown +* List item. +* List item. +* List item. +``` + +**Result** + +* List item. +* List item. +* List item. + +## Definition list {#terms} + +To make a definition list, use the `:` symbol. + +```markdown +Term 1 + +: Definition 1 + +Term 2 + +: Definition 2 +``` + +**Result** + +Term 1 + +: Definition 1 + +Term 2 + +: Definition 2 + +## Nested lists {#sublist} + +To create a nested list, add an indent (from two to five spaces) before the elements of the child list. The recommended indentation is four spaces. + +```markdown +1. First item. + 1. Nested item. + 1. Nested item. +1. Second item. +``` + +**Result** + +1. First item. + 1. Nested item. + 1. Nested item. +1. Second item. + +```markdown +* List item. + * Nested item. + * Nested item. +* List item. +``` + +**Result** + +* List item. + * Nested item. + * Nested item. +* List item. + +``` +Term 1 + +: Definition 1 + + Term 1.1 + + : Definition 1.1 + +Term 2 + +: Definition 2 +``` + +**Result** + +Term 1 + +: Definition 1 + + Term 1.1 + + : Definition 1.1 + +Term 2 + +: Definition 2 + diff --git a/en/syntax/media.md b/en/syntax/media.md new file mode 100644 index 00000000..82f0a8c0 --- /dev/null +++ b/en/syntax/media.md @@ -0,0 +1,64 @@ +# Media + +## Images {#images} + +{% note warning %} + +Images should be stored in a directory whose name starts with `_`. Otherwise, they will be deleted when making a build. + +{% endnote %} + +The standard markup for inserting an image is: + +``` +![alt-text](_images/image.png "hint_text" =100x100) +``` + + * `alt-text`: Alternative image text. + * `_images/image.png`: The URL or path to the image file. + * `"hint_text"`: A hint that will be displayed when you hover over the image. Optional. + * `=100x100`: The image size. Optional. + + {% note tip %} + + If you want to keep the aspect ratio of your image, only specify its width: `100x`. + + {% endnote %} + +### Images as links {#image-link} + +You can make an image clickable using [link design rules](./links.md). To do this, add the standard image markup to the part where the link text usually goes. + +```markdown +[![An old rock in the desert](../../_images/mountain.jpg "Mountain" =100x200)](https://yandex.com/images/search?text=mountain) +``` + +**Result** + +[![An old rock in the desert](../../_images/mountain.jpg "Mountain" =100x200)](https://yandex.com/images/search?text=mountain) + +### Reference-style markup for images {#reference-style} + +Similarly to [reference-style links](./links.md#reference-style), you can declare an image in a special place once and refer to it using a tag throughout the document. This will allow you to use the image multiple times without overloading the text with long URLs or other parameters. + +```markdown +![An old rock in the desert][image1] + +[image1]: ../../_images/mountain.jpg "Mountain" +``` + +**Result** + +![An old rock in the desert][image1] + +[image1]: ../../_images/mountain.jpg "Mountain" +## Videos {#video} + +To add videos to a page, use markup: + +```markdown +@[video_hosting_site_name](video_id_or_link_to_video) +``` + +To review the style options and list of available video hosting services, see the [markdown-it-video](https://www.npmjs.com/package/markdown-it-video) plugin page. + diff --git a/en/syntax/meta.md b/en/syntax/meta.md new file mode 100644 index 00000000..6f118e43 --- /dev/null +++ b/en/syntax/meta.md @@ -0,0 +1,23 @@ +# Comments and metadata + +Comments and metadata are markup elements that are not displayed in the built file. They're used to store information in the source text for SEO or the authors of the document. + +## Comments {#comments} + +To add a comment, use the following markup. Make sure there is an empty line before the comment. + +```markdown +[//]: # (Comment) +``` + +## Metadata {#meta} + +You can add metadata in YAML format at the beginning of a file. After conversion, it is returned with the resulting HTML. + +```yaml +--- +title: Title +description: Description +--- +``` + diff --git a/en/syntax/notes.md b/en/syntax/notes.md new file mode 100644 index 00000000..e50c7dc1 --- /dev/null +++ b/en/syntax/notes.md @@ -0,0 +1,122 @@ +# Notes + +A note is a highlighted block that contains important information. + +Depending on the content, notes with different titles and formatting are used: + +* Note: Additional information. +* Advice: A recommendation. +* Important: A warning. +* Attention: A restriction. +* A note with its own header. + +Notes can include any YFM markup, but we don't recommend overloading them with elements. Choose a simple design and don't overuse notes because this will distract the user from the main content. + +## Comment + +```markdown +{% note info %} + +This is info. + +{% endnote %} +``` + +**Result** + +{% note info %} + +This is info. + +{% endnote %} + +## Tip + +```markdown +{% note tip %} + +This is a tip. + +{% endnote %} +``` + +**Result** + +{% note tip %} + +This is a tip. + +{% endnote %} + +{% endcut %} + +## Warning + +```markdown +{% note warning %} + +This is a warning. + +{% endnote %} +``` + +**Result** + +{% note warning %} + +This is a warning. + +{% endnote %} + +## Alert + +```markdown +{% note alert %} + +This is an alert. + +{% endnote %} +``` + +**Result** + +{% note alert %} + +This is an alert. + +{% endnote %} + +## Custom header + +```markdown +{% note info "Custom header" %} + +This is a note with its own header. + +{% endnote %} +``` + +**Result** + +{% note info "Custom header" %} + +This is a note with its own header. + +{% endnote %} + +```markdown +{% note info "" %} + +This is a note without a header. + +{% endnote %} +``` + +**Result** + +{% note info "" %} + +This is a note without a header. + +{% endnote %} + diff --git a/en/syntax/tables/gfm.md b/en/syntax/tables/gfm.md new file mode 100644 index 00000000..6f32db9b --- /dev/null +++ b/en/syntax/tables/gfm.md @@ -0,0 +1,52 @@ +# GFM Tables + +Tables with syntax similar to tables in GitHub Flavored Markdown. Suitable for simple tables with single-line content in cells. + +{% note tip %} + +To quickly create tables, you can use online generators. For example, [Tables Generator](https://www.tablesgenerator.com/markdown_tables). + +{% endnote %} + +A table consists of: + +* A header row. +* A separator row. +* Rows with data. + +The header row is separated from table cells by three or more `-` characters. Columns are separated by `|`. + +```markdown +| Header 1 | Header 2 | +| ----------- | ----------- | +| Text | Text | +| Text | Text | +``` + +**Result** + +| Header 1 | Header 2 | +| ----------- | ----------- | +| Text | Text | +| Text | Text | + +In the table cells, you can use [line formatting](../base.md#line), [links](../links.md), [single-line code snippets](../code.md#inline), and [images](../media.md#images). + +## Text alignment + +Use the `:` symbol in the separator row to align the text in the columns to the left, right, or center. + +```markdown +| Align left | Align center | Align right | +| :--- | :----: | ---: | +| Text | Text | Text | +| Text | Text | Text | +``` + +**Result** + +| Left-aligned | Centered | Right-aligned | +| :--- | :----: | ---: | +| Text | Text | Text | +| Text | Text | Text | + diff --git a/en/syntax/tables/multiline.md b/en/syntax/tables/multiline.md new file mode 100644 index 00000000..ec1e4100 --- /dev/null +++ b/en/syntax/tables/multiline.md @@ -0,0 +1,99 @@ +# Multiline tables + +Tables with support inside cells for more than just simple content. Example, [lists](../lists.md), [code snippets](../code.md) and other tables. + +### Syntax {#syntax} + +* a table starts with `#|` and ends with `|#`; +* lines start and end with `||`; +* the cells are separated by a symbol `|`. + +{% note tip "Headers of table" %} + +Multiline tables do not contain headers, but they can be done by applying formatting to the content of the cells of the first row. For example, highlighting them in bold. + +{% endnote %} + +```markdown +#| +|| **Header1** | **Header2** || +|| Text | Text || +|# +``` + +**Result** + +#| +|| **Header1** | **Header2** || +|| Text | Text || +|# + +### Multiline content {#multirow} + +Any multiline content can be placed in a table cell. For example, lists. + +```markdown +#| +||Text +on two lines +| +- Potatoes +- Carrot +- Onion +- Cucumber|| +|# +``` + +**Result** + +#| +||Text +on two lines +| +- Potatoes +- Carrot +- Onion +- Cucumber|| +|# + +or even other table: + +```markdown +#| +|| 1 +| + +Text before other table + +#| +|| 5 +| 6|| +|| 7 +| 8|| +|# + +Text after other table|| +|| 3 +| 4|| +|# +``` + +**Result** + +#| +|| 1 +| + +Text before other table + +#| +|| 5 +| 6|| +|| 7 +| 8|| +|# + +Text after other table|| +|| 3 +| 4|| +|# diff --git a/en/syntax/term.md b/en/syntax/term.md new file mode 100644 index 00000000..b6b24d2c --- /dev/null +++ b/en/syntax/term.md @@ -0,0 +1,30 @@ +[*term]: Explaining a term or abbreviation using definition syntax. +The _term_ definition may *include* [basic markup](base.md): +* lists; +* links; +* images, etc. + +# Definition + +The syntax for definitions is: + +``` +[*term_key]: Explaining a term or abbreviation using definition syntax. +The term definition may include _basic_ markup. + +Use of the [term](*term_key) in the text. +``` + +**Result** + +Use of the [term](*term) in the text. + +You can define terms anywhere on the page. + +{% note info %} + +At the moment, the use of definitions in code blocks is possible only if the code block does not have a language specified. + +{% endnote %} + +![terms_sample](../_images/terms_sample.png) diff --git a/en/syntax/vars.md b/en/syntax/vars.md new file mode 100644 index 00000000..f396a85a --- /dev/null +++ b/en/syntax/vars.md @@ -0,0 +1,168 @@ +# Variables + +You can declare a variable in one of the following ways: + +* Pass it in the settings when [building documentation](../tools/docs/index.md#use). +* Describe it in a [file with variable presets](../project/presets.md). + +Methods for using variables in documents are discussed below. + +## Substitutions {#subtitudes} + +To substitute a value with a variable in the text, enter the variable name with double curly brackets before and after. + +``` +Some text {{ variable_name }} text continued. +``` + +If the text contains double curly brackets but doesn't require variable substitution, add `not_var` before the construction. + +``` +Some text not_var{{ also_text }} text continued. +``` + +## Conditional operators {#conditions} + +Use the conditional operators `if`, `else`, and `elsif` to include certain text fragments in the document depending on variable values. For example, to build two versions of a document for different operating systems. + +```markdown +{% if OS == 'iOS' %} + +Download the app from the [App Store](https://www.apple.com/ios/app-store/). + +{% else %} + +Download the app from [Google Play] (https://play.google.com). + +{% endif %} +``` + +You can also apply conditional operators to text fragments inside strings. + +```markdown +Some text {% if OS == 'iOS' %} Apple {% else %} Android {% endif %} text continued. +``` + +## Cycles {#cycles} + +Use loops to output repetitive content for each element of an array. Inside the loop, refer to the element as a regular variable, using syntax for [substitutions](#subtitudes). + +``` +{% for variable_name in array_name %} + +Some text {{ variable_name }} text continued. + +{% endfor %} +``` + +{% cut "Examples of using loops" %} + +Let's say that in a [file with variable presets](../project/presets.md), the `users` array is set: + +```yaml +default: + users: + - Alice + - Mark +``` + +Then using loops will result in the following: + +```markdown +Prefix {% for user in users %} {{user}} {% endfor %} Postfix +``` + +Prefix Alice Mark Postfix + +```markdown +Prefix + +{% for user in users %} + +{{user}} + +{% endfor %} + +Postfix +``` + +Prefix +Alice +Mark +Postfix + +{% endcut %} + +## Filters {#filters} + +To apply a filter, add the `|` operator and the filter name to the variable. Separate the operator with spaces before and after. + +| Filter | Description | +| --- | --- | +| `capitalize` | Makes the first letter in the variable value upper case. | +| `length` | Calculates the length of the variable value. | + +{% cut "Examples of using filters" %} + +Let's say the following is set in a [file with variable presets](../project/presets.md): + +```yaml +default: + user: + name: alice + users: + - Alice + - Mark +``` + +Then using filters will result in the following: + +```markdown +Hello {{ user.name | capitalize }}! +``` + +Hello Alice! + +```markdown +{{ users | length }} + +{{ user.name | length }} | length +``` + +2 + +5 + +{% endcut %} + +## Functions {#functions} + +To invoke a function, add the `.` symbol to the variable, specify its name, and pass the necessary parameters in parentheses `()`. + +| Function | Description | Parameters | +| --- | --- | --- | +| `slice(beginIndex, endIndex)` | Returns the specified part of the source array as a new array object. | `beginIndex` is an index of the element the selection begins with (numbering starts with 0).

`endIndex` is an index of the element the selection ends with (numbering starts with 0). If the parameter is omitted, all elements from the starting position to the end of the array are selected. | + +{% cut "Examples of using functions" %} + +Let's say the following is set in a [file with variable presets](../project/presets.md): + +```yaml +default: + user: + name: Masha +``` + +Then using functions will result in the following: + +```markdown +Hello P{{ user.name.slice(1) }}! + +Hello P{{ user.name.slice(1, 2) }}vel! +``` + +Hello Pasha! + +Hello Pavel! + +{% endcut %} diff --git a/en/toc.yaml b/en/toc.yaml new file mode 100644 index 00000000..12312329 --- /dev/null +++ b/en/toc.yaml @@ -0,0 +1,95 @@ +title: Diplodoc +href: index.yaml +items: + - name: Overview + href: about.md + - name: Quick start + href: how-it-work.md + - name: Yandex Flavored Markdown + expanded: true + href: index-yfm.md + items: + - name: Syntax + items: + - name: Overview + href: syntax/index.md + - name: Basic markup + href: syntax/base.md + - name: Lists + href: syntax/lists.md + - name: Tables + items: + - name: GFM Tables + href: syntax/tables/gfm.md + - name: Multiline tables + href: syntax/tables/multiline.md + - name: Notes + href: syntax/notes.md + - name: Cuts and tabs + href: syntax/cuts-tabs.md + - name: Links + href: syntax/links.md + - name: Media + href: syntax/media.md + - name: Code snippets + href: syntax/code.md + - name: Comments and metadata + href: syntax/meta.md + - name: Variables + href: syntax/vars.md + - name: Definition + href: syntax/term.md + - name: Additional features + href: syntax/additional.md + - name: Settings + href: settings.md + - name: Tools + items: + - name: Transformer + items: + - name: Overview + href: tools/transform/index.md + - name: Settings + href: tools/transform/settings.md + - name: Syntax highlighting + href: tools/transform/highlight.md + - name: Builder + items: + - name: Overview + href: tools/docs/index.md + - name: Build + href: tools/docs/build.md + - name: Translate + href: tools/docs/translate.md + - name: Settings + href: tools/docs/settings.md + - name: Single-page build + href: tools/docs/singlepage.md + - name: Uploading to S3 + href: tools/docs/publish-s3.md + - name: Plugins + items: + - name: Overview + href: plugins/index.md + - name: Adding additional plugins + href: plugins/import.md + - name: Organizing a YFM project + items: + - name: Overview + href: project/index.md + - name: Contents + href: project/toc.md + - name: Leading page + href: project/leading-page.md + - name: Variable presets + href: project/presets.md + - name: Configuration file + href: project/config.md + - name: Reusing content + href: project/includes.md + - name: Linter configuration file + href: project/lint.md + - name: Making edits + href: contribution.md + - name: YFM releases + href: changelog.md diff --git a/en/tools/docs/build.md b/en/tools/docs/build.md new file mode 100644 index 00000000..ca640f68 --- /dev/null +++ b/en/tools/docs/build.md @@ -0,0 +1,30 @@ +# Build + +The [package](https://www.npmjs.com/package/@doc-tools/docs) provides the `yfm` CLI command. + +## HTML {#html} + +Default output format of the builder is html + +To start rendering, run the command specifying the required [startup keys](settings.md): + +* `--input, -i`: The path to the project folder. +* `--output, -o`: The path to the folder for output data (static HTMLs). + +```shell script +yfm -i ./input-folder -o ./ouput-folder +``` + +## YFM {#yfm} + +You can choose to build project in YFM. + +To do this, when executing the `yfm` command, specify the startup key `--output-format=md`. + +Building in YFM allows you to use: + +* [Inserts](../../project/toc.md#includes) and [section visibility conditions](../../project/toc.md#when) in tables of contents files. +* [Content visibility conditions](../../syntax/vars.md#conditions) on document pages. +* [Variable substitutions](../../syntax/vars.md#subtitudes) if the `apply-presets` parameter is specified. + +Use this type of build to support multiple document versions for different users. For example, if there are sections with internal information in the documentation, you can keep two repositories: private and public, and synchronize private with public using conditions. diff --git a/en/tools/docs/index.md b/en/tools/docs/index.md new file mode 100644 index 00000000..66849e2b --- /dev/null +++ b/en/tools/docs/index.md @@ -0,0 +1,18 @@ +# Builder + +[@doc-tools/docs](https://www.npmjs.com/package/@doc-tools/docs) is a package for building a documentation project with navigation, internal transitions, and full support for Yandex Flavored Markdown. + +A built project is a set of static HTML files that can be viewed locally or on a host, in GitHub Pages, or in [S3](publish-s3.md). + +## Installation {#install} + +To install the package, run this command: + +```shell +npm i @doc-tools/docs -g +``` + +## Commands + +- [Build](./build.md) +- [Translate](./translate.md) diff --git a/en/tools/docs/publish-s3.md b/en/tools/docs/publish-s3.md new file mode 100644 index 00000000..d545da36 --- /dev/null +++ b/en/tools/docs/publish-s3.md @@ -0,0 +1,19 @@ +# Uploading to S3 + +You can configure the building so that the documentation is automatically uploaded to [S3 storage](https://cloud.yandex.com/services/storage). To do this, when executing the `yfm` command, specify the `--publish` startup key. + +You can set layout settings in one of the following ways: + +* Using startup keys: The name of the key corresponds to the name of the setting. +* In a [configuration file](../../project/config.md). + +## Uploading settings {#settings} + +| Configuration | Description | +| --- | --- | +| `storageEndpoint` | Endpoint for S3 storage. | +| `storageBucket` | Bucket. | +| `storageKeyId` | Authorization key ID.

Can be set in the `YFM_STORAGE_KEY_ID` environment variable. | +| `storageSecretKey` | Authorization key.

Can be set in the `YFM_STORAGE_SECRET_KEY` environment variable. | +| `storagePrefix` | Prefix for file paths.

Optional parameter. Can be used to pass the build version, so each build is placed in a separate folder. | + diff --git a/en/tools/docs/settings.md b/en/tools/docs/settings.md new file mode 100644 index 00000000..b496fa8f --- /dev/null +++ b/en/tools/docs/settings.md @@ -0,0 +1,29 @@ +# Build settings + +The build settings are listed below. You can configure them and [standard YFM settings](../../settings.md) in one of the following ways: + +* Using startup keys when executing the `yfm` command. +* In a [configuration file](../../project/config.md). + +The name of the startup key corresponds to the name of the setting. + +| Startup key | Description | +|-----------------------------| --- | +| `--input, -i` | Path to the project directory (required parameter). | +| `--output, -o` | The path to the folder for output data (required parameter). | +| `--varsPreset` | Name of the [variable preset](../../project/presets.md) used. | +| `--vars, -v` | Values of [variables](../../syntax/vars.md). | +| `--strict, -s` | Launch in strict mode.

YFM warnings are treated as errors. Disabled by default. | +| `--quiet, -q` | Start in quiet mode.

Do not output logs to stdout. Disabled by default. | +| `--config, -c` | Path to the [configuration file](../../project/config.md). | +| `--singlePage` | Build the project as a single HTML file. For more information, see [Single-page build](./singlepage.md). | +| `--output-format` | Generation format. HTML by default, but you can choose to [build in YFM](build.md#yfm). | +| `--apply-presets` | Substitute variable values from presets when building in YFM. | +| `--add-system-meta` | Add variables from the system presets section to [metadata](../../syntax/meta.md#meta) files. Disabled by default. | +| `--remove-hidden-toc-items` | Remove hidden pages from the build result. Disabled by default. | +| `--version` | Current version. | +| `--lint-disabled` | Should whether to turn off a linter | +| `--build-disabled` | Should whether to turn off a build | +| `--add-map-file` | Should add all paths of documentation into file.json. Disabled by default. | + +To view the full list of keys, run the `yfm --help` command. diff --git a/en/tools/docs/singlepage.md b/en/tools/docs/singlepage.md new file mode 100644 index 00000000..95b9028e --- /dev/null +++ b/en/tools/docs/singlepage.md @@ -0,0 +1,10 @@ +# Single-page build + +You can build an entire project as a single HTML file. To do this, when executing the `yfm` command, specify the `--single-page` startup key. + +{% note warning "Beta function" %} + +This is currently a beta function, so it may not work well on large projects with a complex structure. If you have any problems, let us know on [GitHub issues](https://github.com/yandex-cloud/yfm-docs/issues). + +{% endnote %} + diff --git a/en/tools/docs/translate.md b/en/tools/docs/translate.md new file mode 100644 index 00000000..1ac78b5d --- /dev/null +++ b/en/tools/docs/translate.md @@ -0,0 +1,43 @@ +# Translate + +`yfm translate` translates your documentation using [Yandex Translator](https://cloud.yandex.com/en/docs/translate/) + +## Setup + +- get your OAUTH token as described in [yandex.cloud documentation](https://cloud.yandex.com/en/docs/iam/concepts/authorization/oauth-token) + +- put it inside `.ya_oauth_token` file inside home folder or set it with `YANDEX_OAUTH_TOKEN` environment variable + +- get the ID of any folder that your account is granted the editor role or higher for as described in [yandex.cloud documentation](https://cloud.yandex.com/en/docs/resource-manager/operations/folder/get-id) + +- set `yandexCloudTranslateFolderId` inside `.yfm` config file to folder id you got from previous step + +- set `yandexCloudTranslateGlossaryPairs` inside `.yfm` config file if you need to use glossary dictionary while translating (example below) + +``` +# glossary example + +yandexCloudTranslateGlossaryPairs: + - { sourceText: InstreamAdBreakPositionType, translatedText: InstreamAdBreakPositionType } +``` + +_This will make **InstreamAdBreakPositionType** stay without change in the target(translated) document_ + +Now you can use yfm cli to translate your documentation. + +## Flags + +| Option name | required | value | description | +| ----------------- | -------- | ------------- | ---------------------------------------------------------------------------- | +| --input | yes | path | source path to the documentation | +| --output | yes | path | target path to the translated documentation | +| --source-language | yes | language code | language code in [ISO 639-1 format](https://en.wikipedia.org/wiki/ISO_639-1) | +| --target-language | yes | language code | language code in [ISO 639-1 format](https://en.wikipedia.org/wiki/ISO_639-1) | + +## Usage + +``` +yfm translate --input input_folder --output output_folder --source-language ru --target-language en +``` + +_This will translate your russian documentation in the **input_folder** into english one putting it to **output_folder**_ diff --git a/en/tools/transform/highlight.md b/en/tools/transform/highlight.md new file mode 100644 index 00000000..4dd97966 --- /dev/null +++ b/en/tools/transform/highlight.md @@ -0,0 +1,66 @@ +# Syntax highlighting + +The [highlight.js](https://www.npmjs.com/package/highlight.js) package is used to highlight code. For the list of available languages, see [Github](https://github.com/highlightjs/highlight.js/tree/master/src/languages). + +To install the package, run this command: + +```shell +npm i highlight.js +``` + +## Supported Languages + +Key used to enable syntax highlighting inside the code block. + +* apache +* bash +* coffeescript +* cpp +* cs +* css +* diff +* go +* http +* ini +* java +* javascript +* json +* kotlin +* less +* lua +* makefile +* xml +* markdown +* nginx +* objectivec +* perl +* php +* plaintext +* properties +* python +* ruby +* rust +* scss +* shell +* sql +* swift +* typescript +* yaml + +## Adding other languages {#add} + +You can pass an additional set of languages that will be registered for use. + +A set of languages is passed as an object, with: + +* The name of the language as the key. +* A function that defines the language as the value. + +```javascript +const transform = require('@doc-tools/transform'); +const customLang = require('./custom-lang'); + +const highlightLangs = { 'custom-lang': customLang }; + +const {result: {html, meta}, logs} = transform(content, {highlightLangs}); +``` diff --git a/en/tools/transform/index.md b/en/tools/transform/index.md new file mode 100644 index 00000000..8e440890 --- /dev/null +++ b/en/tools/transform/index.md @@ -0,0 +1,69 @@ +# Transformer + +[@doc-tools/transform](https://www.npmjs.com/package/@doc-tools/transform) is a package for converting Yandex Flavored Markdown to HTML. + +Use it in your code to work with text during program execution. For example, to display user-generated content. + +## Installation {#install} + +1. Install a package: + + ```shell + npm i @doc-tools/transform + ``` + +1. Add the package in your code using the `require()` or `import()` function: + + ```javascript + const transform = require('@doc-tools/transform'); + ``` + +1. To ensure text is displayed properly, add CSS styles and client scripts to the project: + + ```css + @import '~@doc-tools/transform/dist/css/yfm.css'; + ``` + + ```javascript + import '@doc-tools/transform/dist/js/yfm'; + ``` + +## Usage {#use} + +The package provides the `transform()` function: + +* Input data: [Settings](settings.md) and a string with YFM. +* Returned value: An object with the `result` and `logs` fields. + +### Result field + +`result`: Resulting object, contains the fields: + +* `html`: A line with HTML. +* `meta`: [Metadata](../../syntax/meta.md#meta) from the transmitted content. +* `title`: The document title. Returned if `extractTitle = true` or `needTitle = true`. +* `headings`: A list of document headers. + +### Logs field + +`logs`: Information about the transformation process, includes arrays: + +* `error`: Errors. +* `warn`: Warnings. +* `info`: Additional information. + +### Example of a function invocation + +```javascript +const fs = require('fs'); +const transform = require('@doc-tools/transform'); + +const content = fs.readFileSync(filePath, 'utf'); +const vars = { user: { name: 'Alice' } }; + +const { + result: {html, meta, title, headings}, + logs, + } = transform(content, {vars}); +``` + diff --git a/en/tools/transform/settings.md b/en/tools/transform/settings.md new file mode 100644 index 00000000..ba8a6992 --- /dev/null +++ b/en/tools/transform/settings.md @@ -0,0 +1,15 @@ +# Transformation settings + +The transformation settings are listed below. You can configure them and [standard YFM settings](../../settings.md) in one of the following ways: + +* When invoking the `transform` function. +* In a [configuration file](../../project/config.md). + +| Name | Description | Type | Default value | +| --- | --- | --- | --- | +| `plugins` | Added plugins | `function[]` | See the [Plugins](../../plugins/index.md) page | +| `highlightLangs` | Additional languages for [code highlighting](highlight.md) | `{'lang': function}` | `{}` | +| `extractTitle` | Return the first first-level header as the title of the entire document | `bool` | `false` | +| `needTitle` | Return the first first-level header without removing it from the document text | `bool` | `false` | +|`needFlatListHeadings` | Generate a flat list of all headers in a document | `bool` | `false` | +