reporting-docs

Содержание

Front Matter (Metadata Block or Article Header Section)
URL Redirects
Titles and Headings
Tables

Inline Code Snippets inside Tables
Using CSS

Using HTML
Code Snippets in Text

Inline Code Snippets
Code Snippets without Special Characters
Programming Language Snippets with Any Content

Code Snippets in Lists
Code Snippets in Notes
Lists
Links
Notes, Warnings, and Other Special Messages
Use Special Symbols
Images
Headers that Generate Anchor/Hashtag Links
The See Also Section

As a general guide for structuring the Markdown (MD) document, you may follow the article Markdown Cheatsheet.

However, due to the specifics of the Telerik Reporting infrastructure and building process, you have to consider the guidelines listed in this article so that the builds run successfully and the documentation gets uploaded smoothly.

The Preview of the MD documents in GitHub is NOT what will be rendered on the Telerik Reporting website after the documentation is built with Jekyll. Therefore, make sure the specific types of content in MD such as code snippets, lists, tables, headers, and so on, comply with the following rules which cover all currently known issues.

Front Matter (Metadata Block or Article Header Section)

In the article front matter which hosts the main metadata attributes such as the title, page_title, slug, description, and so on, always leave empty space after the ':'. For example, use title: My Article Name and NOT title:My Article Name.
Never change the slug of an article. This will break the documentation build as all references to this article won't be able to find it.
To add an attribute that has to hold no value, place a space " ".
Do NOT use quotation marks like " and ' in the title and page_title, as this breaks the preview.
Do NOT use special characters in the title, page_title, description meta tags such as \, *, %, {, }, [, ], ' and similar.
KB articles should contain the attribute res_type: kb. If it is missing, the title will not appear.

The following example demonstrates the implementation of these rules for the front matter of a sample KB article:

---
title: Actions Not Working on Preview
description: "Learn how to handle cases when some or all report item actions are not working on previewing the report."
type: how-to
page_title: Unable to Use Interactive Actions When Previewing the Report
slug: actions-not-working-on-preview
res_type: kb
---

URL Redirects

To redirect the previous article links to the new one, add the previous_url: in the metadata block. Add a slash (/) before the rule, for example:

previous_url: /report-items/barcode/barcode-types/1d-barcodes

If the previous_url link contains special symbols, escape them. For example, to redirect to the /report-items/automatic-layout-(dock-and-anchor) location, write it as /report-items/automatic-layout-\(dock-and-anchor\).

You can also add two and more previous_url locations by separating them with a comma and adding a space (, ). For example:

previous_url: /designing-reports/report-structure/automatic-layout-\(dock-and-anchor\), /report-items/automatic-layout-\(dock-and-anchor\)

Make sure that each previous_url is included in only one article. Otherwise, the web.config of the documentation will contain more than one redirect rule with the same name and the site will fail.

Titles and Headings

Do NOT use special characters in titles and headings such as \, *, %, {, }, [, ], and similar.

Tables

Generally, MD-styled tables appear with columns of equal width. To individually adjust each column width to its specific content, use either CSS or HTML depending on the table content and the number of tables within the article.

Inline Code Snippets inside Tables

The code must be wrapped with the pre and code tags, for example:

<pre><code>
start code at the beginning of the line, pre and code tags must be on the same line
</code></pre>

For a full example, check the table code snippets at the following slug - telerikreporting/embedding-reports/display-reports-in-applications/web-application/native-blazor-report-viewer/api-reference/options

Using CSS

MD-syntax tables provide fast and handy content management and enable you to use MD-styled links and other MD-formatted content inside. However, by default, the table columns will have equal widths.

To work around this issue, you can add a CSS style block right before the table.

Note that you can use only a single CSS block in each individual article. Otherwise, all tables will finally have the same column width.

The following example assumes the table contains three columns. The first column will take up 20% of the width, the second - 30%, and the third - 50%.

Using HTML

Using HTML will enable you to set each table individually and define the width of its columns as exactly required.

Note that while Markdown allows you to render HTML within MD syntax, HTML does not return the favor. As a result, MD-styled links and MD-formatted content inside the HTML table will deliver as regular text. You need to replace all MD-syntax content within an HTML table with its corresponding HTML tags. For example, MD links [text](URL) have to become <a> tags.

If you have nested tables, you can use both the CSS and the HTML approach to implement the main table. However, nested tables have to be in HTML.
To split the table content and add new lines, use the <br /> HTML tag. Otherwise, new lines will break the table.
For lists inside the table, use the <ul>, <ol>, and <li> HTML-tags to format them properly.

Code Snippets in Text

Introduce snippets with the programming language with four backticks (````).
To provide the name of the programming language, use one word only. For example CSharp or C# and NOT C Sharp or C #.

Inline Code Snippets

To introduce inline code snippets, use a single `, for example:

some text <some xml> more text
Place code snippets inline when the snippets are short. Otherwise, if the snippet is two or more lines, some of the content may be cut.
Avoid ending a line with an inline snippet and a full stop (.) directly after it, as the full stop may be placed on the next line. For example, you may change "gauge Width." with "Width of the gauge." or similar.

Code Snippets without Special Characters

To generate simple code snippets that do not contain special characters, indent the content one TAB further than the rest of the content. For an example, check the Search In Document REST API article.

Programming Language Snippets with Any Content

To introduce and close the code blocks, use four backticks (````).
Use the programming language name after the opening ticks.
The four ticks enable you to format the code as you want it. However, they will prevent you from previewing the MD properly in Github.
Avoid absolutely empty lines in the code snippet. Place at least one TAB in the empty lines. The absolutely empty line may break the snippet in some cases only.
If you want to implement tabbed code blocks, for example, one in C# and one in VB so that you can switch between them, place them immediately one after the other.
Optionally, you can place the source for the code just above the corresponding snippet. When building, a special piece of code will read the actual snippet and update the MD article.

The following example demonstrates the implementation of the listed rules.

{{source=CodeSnippets\CS\API\Telerik\Reporting\ObjectDataSourceSnippets.cs region=SampleDataSource}}

class Product
{
	//properties
}


[DataObject]
class Products
{
	//objects
}

{{source=CodeSnippets\VB\API\Telerik\Reporting\ObjectDataSourceSnippets.vb region=SampleDataSource}}

Class Product
	'properties
End Class

<DataObject()>
Class Products
	'objects
End Class

Code Snippets in Lists

/PLEASE, UPDATE THIS IF YOU FOUND A WAY TO ADD TABBED CODE SNIPPETS UNDER A LIST ITEM WITHOUT BREAKING THE LIST/

In a list item, you can use only untabbed code snippets.
If you need two snippets under the same list item, they need to be displayed one after the other instead of in two tabs of the same code block.
The code snippet is aligned with the starting four backticks (````). Start only the first line from the beginning of the row so that the code is properly aligned and to avoid breaking the appearance when the snippet contains empty lines.
For inline snippets, use a single backtick, for example, some text <some xml> more text.
Leave at least one empty row after each code snippet.

This example from the Telerik Reporting documentation demonstrates the layout that is required to properly render code snippets in lists. Note that:

The code block opener for the VB snippet is not indented as the C# one and this breaks the tabbed appearance of the snippets.
If the second code block (VB) started from the beginning of the row, this would have broken the list.
If the list is unordered, this may still be acceptable, although the code block would appear as a sibling rather than a child of the List.
If the list is ordered though, the next List item will start from 1.
When the list ends with a code snippet, separate the list from the following text by leaving at least two empty lines between them.

Code Snippets in Notes

To be rendered properly, code snippets in notes have to start with a properly indented >````. However, the closing ```` may not have a > in front when the Note is tabbed like in a list.

For examples see:

For a code snippet in a note tabbed in a list: https://github.com/telerik/reporting-docs/edit/master/embedding-reports/display-reports-in-applications/web-application/angular-report-viewer/how-to-use-angular-report-viewer-with-angular-cli.md
For a code snippet just in a note: https://github.com/telerik/reporting-docs/edit/master/designing-reports/report-designer-tools/desktop-designers/tools/edit-expression-dialog.md

Lists

Leave one empty line before starting the list.

The content within the list items has to be properly indented and aligned with the list item content after the list identifier (either a number for ordered lists or a bullet for unordered).

For properly rendering lists in tables, refer to Tables.
For properly rendering code snippets in lists, refer to Code Snippets in Lists.
For using code snippets in the list, use TAB to indent the opening ```` of the snippet and all the new lines that are included in the list item.

Links

When referring to articles from the documentation or KBs, reference them with their corresponding slugs by using the [text to be shown]({%slug referencedArticleSlug%}) syntax. For example, [1D Barcodes]({%slug telerikreporting/designing-reports/report-structure/barcode/barcode-types/1d-barcodes%}).

You can also include references to specific article sections by using their corresponding anchor text after the '#' sign in the URL. For example, [text to be shown]({%slug referencedArticleSlug%}#sectionTitle). Note that sectionTitle from this example is the name of the section in lowercase with all words separated by a dash (-). For example, a section with the Available Report Sources heading will result in available-report-sources as a section title.

The following code will generate the https://docs.telerik.com/reporting/designing-reports/report-sources/overview#available-report-sources link and display the Available Report Sources section of the corresponding article: [server-side ReportSource]({%slug telerikreporting/designing-reports/report-sources/overview%}#available-report-sources).

For links to the API reference use /api/theLinkToTheResource. The leading slash is important to generate the correct URL.

Notes, Warnings, and Other Special Messages

Here is a list with flags for the notes and how they occur in the document:

> or >important: an orange note with (i)

>note or >tip: a green note with a check (v)

>caution or >warning: a red note with an exclamation mark (!)

Slugs DON'T WORK in notes that are flagged with the >tip, >note, >caution, >warning and >important tags. For example, the >important some text [link]({%slug putTheSlugHere%}) link will not work.

To work around this issue, you can use an absolute or relative URL, for example, >important some text [report sources]({../designing-reports/report-sources/overview}). However, this additional approach for implementing links will make the future maintenance of documentation more difficult if we change the location of an article or decide to remove it altogether.

Therefore, it is recommended that you don't use links in the note or just don't flag it as a tip, note, or other. For example, to generate the correct link, use the > some text [link]({%slug putTheSlugHere%}) syntax. We have logged a docs-seed issue on slugs in flagged notes and hope the team will be able to prioritize it in the near future.

Use Special Symbols

When building with Jekyll, the double curly brackets {{ and }} are special symbols. If you need to show them or other special symbols in the MD text, use the following syntax, with opening {%raw%} and closing {%endraw%}:

{%raw%}any text here, including {{ and }} will be shown as it is{%endraw%}

Images

As a general recommendation, always compress the images that you use in the docs.

Headers that Generate Anchor/Hashtag Links

If in the header there is a snippet, i.e. `snippet here`, the Link URL after the hashtag will stop before the snippet. For example, the following headers generate the same link:

Default Configuration for the `.NET` Standalone Report Designer			->	~/overview#default-configuration-for-the
Default Configuration for the `.NET Framework` Standalone Report Designer	->	~/overview#default-configuration-for-the

The See Also Section

To introduce a list item under the See Also section, use the [title](URL to the resource) format. The text you want to display is the text in [title].
If you use the [title](URL to the resource) some more text format, the some more text input will look weird in the built documentation.
Make sure NOT to have spaces after the end of the URL. If you have 2 spaces, this will result in a large space (maybe 2 lines) to the next URL

Specifics When Creating Markdown Articles for Telerik Reporting