Skip to content

fix(okf): satisfy super-linter markdown rules #78

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.

Sign up for GitHub

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

Merged
duyet merged 1 commit into from
Jun 14, 2026
Merged

fix(okf): satisfy super-linter markdown rules #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
36 changes: 19 additions & 17 deletions okf/skills/okf/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ When asked to init/scaffold an OKF bundle at `<path>`:

# <Bundle name>

* [Datasets](datasets/) - <group description>
* [Tables](tables/) - <group description>
- [Datasets](datasets/) - <group description>
- [Tables](tables/) - <group description>
```

4. Add a `references/` directory only if you expect standalone citation docs.
Expand All @@ -73,28 +73,29 @@ asset name where possible.

```markdown
---
type: <Type name> # REQUIRED — e.g. "BigQuery Table", "API Endpoint", "Playbook"
title: <Display name> # strongly recommended
description: <one-line summary> # strongly recommended — used in indexes/previews
resource: <canonical URI> # for assets that have one
tags: [<tag>, <tag>] # optional, cross-cutting
timestamp: <ISO 8601> # optional, last meaningful change
type: <Type name> # REQUIRED — e.g. "BigQuery Table", "API Endpoint", "Playbook"
title: <Display name> # strongly recommended
description: <one-line summary> # strongly recommended — used in indexes/previews
resource: <canonical URI> # for assets that have one
tags: [<tag>, <tag>] # optional, cross-cutting
timestamp: <ISO 8601> # optional, last meaningful change
---

# Schema (when the concept has structured fields — prefer a table)
# Schema (when the concept has structured fields — prefer a table)

| Column | Type | Description |
|--------|------|-------------|
| Column | Type | Description |
| ------ | ---- | ------------------------------ |
| ... | ... | FK to [other](/group/other.md) |

# Examples (concrete usage in code blocks)
# Examples (concrete usage in code blocks)

# Citations (external sources)
# Citations (external sources)

[1] [Title](https://example.com)
```

Guidance:

- Prefer structural markdown (tables, lists, code blocks) over prose paragraphs.
- Express relationships by **linking** related concepts inline in the prose; the
link is an undirected edge in the knowledge graph.
Expand All @@ -109,8 +110,8 @@ pull each bullet's description from the linked concept's `description`:
```markdown
# Tables

* [Orders](orders.md) - one row per completed customer order
* [Customers](customers.md) - one row per customer
- [Orders](orders.md) - one row per completed customer order
- [Customers](customers.md) - one row per customer
```

Use relative links inside an index (they sit beside their targets). Regenerate the
Expand All @@ -124,7 +125,8 @@ Append directory-level history, newest first, ISO dates:
# Directory Update Log

## 2026-06-14
* **Creation**: Added orders and customers tables.

- **Creation**: Added orders and customers tables.
```

## Validate a bundle for OKF v0.1 conformance
Expand All @@ -136,7 +138,7 @@ check, then eyeball the report. It verifies:
- `index.md` / `log.md` carry no frontmatter (root `index.md` may carry only
`okf_version`).
- Reports broken bundle-relative cross-links as warnings (broken links are
*tolerated* by the spec — surface them, don't fail on them).
_tolerated_ by the spec — surface them, don't fail on them).

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/okf/scripts/validate_okf.py ./bundles/my_bundle
Expand Down
45 changes: 24 additions & 21 deletions okf/skills/okf/reference/SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
> anyone can consume it (file servers, Obsidian/Notion/MkDocs, LLMs, search
> indexes, graph viewers).
>
> Source: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
> Source: <https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md>

## Core principles

Expand All @@ -26,7 +26,7 @@

A knowledge bundle is a hierarchical directory of markdown files:

```
```text
bundle_root/
├── index.md (optional; only place frontmatter is allowed in an index)
├── log.md (optional)
Expand All @@ -38,6 +38,7 @@ bundle_root/
```

**Reserved filenames:**

- `index.md` — progressive-disclosure directory listings.
- `log.md` — chronological update history.

Expand All @@ -51,12 +52,12 @@ Two sections: required YAML frontmatter, then a markdown body.

```yaml
---
type: <Type name> # REQUIRED — non-empty string
title: <Display name> # Recommended
description: <One-line summary> # Recommended
resource: <Canonical URI> # Recommended for assets
tags: [<tag>, <tag>] # Optional
timestamp: <ISO 8601 datetime> # Optional
type: <Type name> # REQUIRED — non-empty string
title: <Display name> # Recommended
description: <One-line summary> # Recommended
resource: <Canonical URI> # Recommended for assets
tags: [<tag>, <tag>] # Optional
timestamp: <ISO 8601 datetime> # Optional
# Producers may add arbitrary custom keys.
---
```
Expand All @@ -78,11 +79,11 @@ on round-trips.
Standard markdown. Conventional section headings (prefer structural markdown —
tables, lists, code blocks — over prose):

| Section | Purpose |
|---------------|-----------------------------------------------|
| `# Schema` | Structured description of columns/fields. |
| `# Examples` | Concrete usage examples in code blocks. |
| `# Citations` | External sources supporting claims. |
| Section | Purpose |
| ------------- | ----------------------------------------- |
| `# Schema` | Structured description of columns/fields. |
| `# Examples` | Concrete usage examples in code blocks. |
| `# Citations` | External sources supporting claims. |

## Cross-linking

Expand All @@ -102,12 +103,12 @@ Optional, support progressive disclosure. Sections group concepts. No frontmatte
```markdown
# Section Heading

* [Title](relative-url) - description from the linked concept
* [Subdirectory](subdir/) - group description
- [Title](relative-url) - description from the linked concept
- [Subdirectory](subdir/) - group description

# Another Section

* [Title](url) - description
- [Title](url) - description
```

Producers may generate them automatically; consumers may synthesize dynamically.
Expand All @@ -121,11 +122,13 @@ Date headings must use ISO 8601 `YYYY-MM-DD`. Leading bold words are conventiona
# Directory Update Log

## 2026-05-22
* **Update**: Description of change
* **Creation**: Description of new content

- **Update**: Description of change
- **Creation**: Description of new content

## 2026-05-15
* **Initialization**: Foundational changes

- **Initialization**: Foundational changes
```

## Citations
Expand Down Expand Up @@ -166,7 +169,7 @@ Best-effort consumption is preferred over rejection.

## Minimal example

```
```text
my_bundle/
├── index.md
├── datasets/
Expand Down Expand Up @@ -209,7 +212,7 @@ timestamp: 2026-05-28T00:00:00Z
# Schema

| Column | Type | Description |
|---------------|---------|------------------------------------------|
| ------------- | ------- | ---------------------------------------- |
| `order_id` | STRING | Unique order identifier. |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |
| `total_usd` | NUMERIC | Order total in USD. |
Expand Down
Loading