Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add YAML metadata guideline #1189

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ The document covers the process for contributing to the articles and code sample
1. [Repository structure](#repository-structure)
1. [File Name](#file-name)
1. [Naming Rules for Tizen Terms](./styleguide/naming-rules.md)
1. [YAML metadata in Tizen documentents](./styleguide/yaml-metadata.md)
1. [DOs and DON'Ts](#dos-and-donts)
1. [Content license](#content-license)
1. [Contributor License Agreement](#contributor-license-agreement)
Expand Down
104 changes: 104 additions & 0 deletions styleguide/yaml-metadata.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# YAML metadata in Tizen documentents

This guideline describes YAML syntax and YAML meta.

The following code shows the YAML metadata in Tizen documents.

## Syntax

All YAML files can optionally begin with `---` and end with `---`. This is part of the YAML format and indicates the start and end of a document.


A dictionary is represented in a simple `key: value` form (the colon must be followed by a space):
```
---
title: YAML metadata in Tizen documentents
author: Anonymous (anonymous@tizen.org)
summary: YAML metadata guideline
keyword: YAML, metadata, Tizen, YAML syntax
redirect: overview
---
```

## YAML elements

The Tizen documentation has various YAML elements.

### title

There is no title in menu, the title in meta displays displays this title.

```
---
title: YAML metadata in Tizen documentents
---
```

### author

The Tizen repository is in public GitHub so we don't know the exact the document authors.
When the authors are listed, it helps to contact the authors when there are issues.
Copy link
Contributor

@mijin85cho mijin85cho Jul 30, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small question. If another person, who is not the author updates or enhances the page, how should we change the author?


```
---
author: Anonymous (anonymous@tizen.org)
---
```

### summary

Summary describes what the document is briefly.

```
---
summary: YAML metadata guideline
---
```

### keyword

Keywords in the document are extracted automatically when a Pull Request is sent. The extracted keywords are words list. Words are split by a space. In other words, it can't detect collocations with space such as "heavy rain", "high temperature", and "have an experience".
However, you can manually insert keywords at the beginning of documents to improve Search Engine Optimization (SEO).

```
---
keyword: Tizen, guidleline, YAML syntax
---
```
In the above example, "YAML syntax" is a kind of collocations.

### redirect

Redirect allows the page jump the other page. For example, there is a representative page, which is a root having lots of children.
In general, when there is `index.md` in the root directory, and children in subdirectories.

For example, Your documents exist in folders as the follows:
```
root
├── build
│   └── package.md
├── index.md
└── setup
└── overview.md
└── install.md

```

You want to show the overview page, as soon as a user click the root page. In this case, `index.md` has only YAML metadata.

The following YAML meta can fulfill your requirement.

```
---
redirect: setup/overview
---
```

###

## Related information

- [YAML](https://yaml.org/)
- [YAML Syntax](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html)
- [Metadata in Microsoft Word documents](https://blog.martinfenner.org/2015/03/20/metadata-in-microsoft-word-documents/)