Use of YAML files in engineering-astro in [#technical-documentation]

YAML usage overview

YAML files are structured data files, similar to JSON. Within the engineering-astro repository, YAML files are used in multiple scenarios to ensure content consistency and ease of maintenance.

The purpose of this note is to provide an explanation of the below YAML file use cases within the engineering-astro repository.

Technical library topics

Each technical library topic has a topic.yaml file found inside the library topic’s directory.

```
@startsalt
{
   {T
      + src/
      ++ pages/
      +++ topics/
      ++++ [topic]/
      +++++ **topic.yaml**
   }
}
@endsalt
```

These files are read by:

• /src/lib/topics.ts to build content for the technical library index
• /src/layouts/TopicLayout.astro which provides the topic card (see on the right side of this page for example) and formatting for all topic pages (articles, notes, links).

An example topic.yaml file contains the below values:

layout: "$/layouts/TopicLayout.astro"
name: git
title: Git
description: Git and version control best practices and standards
website: https://git-scm.com
documentation: https://git-scm.com
logo: /img/icons/git-logo.svg
backgroundImageUrl: /img/icons/git-logo.svg

Topic rules

Inside each library topic an optional rules directory may be found. This directory contains rules or standards and related examples defined in YAML format.

```
@startsalt
{
   {T
      + src/
      ++ pages/
      +++ topics/
      ++++ [topic]/
      +++++ rules/
      ++++++ **example-rule1.yaml**
      ++++++ **example-rule2.yaml**
   }
}
@endsalt
```

Only one rule is defined within each YAML file to ensure each rule can be referenced with a distinct URL.

These files are read by: src/pages/topics/[topicName]/rules.astro to create the topic’s rule navigation and content.

An example topic rule contains the below values:

title: yaml-file-extension
state: active
   rule: All Ansible Yaml files MUST have a .yml extension (and NOT .YML, .yaml, etc.).
   rationale: |
   Ansible tooling (like ansible-galaxy init) creates files with a .yml extension.
   Also, the Ansible documentation website references files with a .yml extension several times.
   Because of this, it is normal in the Ansible community to use a .yml extension for all Ansible Yaml files.
examples:
   bad:
      - language: sh
         code: example.yaml
      - language: sh
         code: example.YAML
   good:
      - language: sh
         code: example.yml

Jobs and gigs

Within /src/pages/jobs/yaml are structured data files providing relevant information about roles and gigs at LinkORB.

```
@startsalt
{
   {T
      + src/
      ++ pages/
      +++ jobs/
      +++++ yaml/
      ++++++ **job1.yaml**
      ++++++ **job2.yaml**
      ++++ gigs/
      +++++ yaml/
      ++++++ **gig1.yaml**
      ++++++ **gig2.yaml**
   }
}
@endsalt
```

These files are read by:

• src/pages/jobs/index.astro to build content for the job index page
• src/pages/jobs/[…job].astro to create routes and rendered HTML for individual roles and gigs

Given the length of these files, to review an example please refer to the files within /src/pages/jobs/yaml/ and /src/pages/gigs/yaml/ directories.

Badges

Within /src/pages/badges/yaml/ are structured data files providing relevant information about badges at LinkORB.

```
@startsalt
{
   {T
      + src/
      ++ pages/
      +++ badges/
      ++++ yaml/
      +++++ **badge1.yaml**
      +++++ **badge2.yaml**
   }
}
@endsalt
```

These files are read by:

• src/pages/badges/index.astro to build content for the badge index page
• src/pages/badges/[…badge].astro to create routes and rendered HTML for individual badges

Given the length of these files, to review an example please refer to the files within /src/pages/badges/yaml directory.

Links

Each library topic may include an optional links folder containing YAML-formatted links to useful resources. For example, the ssh.yaml file in the links folder of the below example may contain multiple links to SSH server and client security best practices.

@startsalt
{
   {T
      + src/
      ++ pages/
      +++ topics/
      ++++ security/
      ++++ **links**
      +++++ **misc.yaml**
      +++++ **ssh.yaml**
   }
}
@endsalt

Such YAML files are read by:

• src/lib/yaml.ts to parse the YAML formatted content (links) as JavaScript objects.
• src/pages/topics/[topicName]/links.astro to render each link section to the user interface.

See add a resource link to a topic for more information.