Skip to content

Commit f729f8d

Browse files
vishalvivekmvishalvivekm
authored
Merge pull request #520 from vishalvivekm/vishalvivekm-patch-1
Create contributing video guide
2 parents 4f030e1 + 171d18e commit f729f8d

File tree

7 files changed

+166
-1
lines changed

7 files changed

+166
-1
lines changed

‎content/en/contributing/_index.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Contributing
3+
description: Contributing guides on documentation and video gallery
4+
type: docs
5+
cascade:
6+
type: docs
7+
---

‎content/en/kanvas/reference/contributing-to-docs.md renamed to ‎content/en/contributing/contributing-to-docs.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
22
title: Contributing to Layer5 Docs
3-
weight: 10
3+
weight: 1
44
description: A detailed contribution guide for Layer5 Docs.
55
aliases:
66
- /meshmap/reference/contributing-to-docs
7+
- /kanvas/reference/contributing-to-docs/
78
---
89

910
Welcome to the GitHub repository for Layer5's documentation website!

‎content/en/contributing/contributing-to-video-gallary.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Contributing to Video Gallery
3+
weight: 1
4+
description: A detailed contribution guide for adding videos to Layer5 Docs video gallary
5+
---
6+
7+
{{< alert title="Note" >}}In Hugo, a section is a directory containing an `_index.md` file.{{< /alert >}}
8+
9+
## Overview
10+
11+
Contributing videos involves either:
12+
1. Creating a category → subcategory → adding video markdown files, or
13+
2. Adding video markdown files directly under a category (these will automatically be assigned to an "ALL" subcategory)
14+
15+
## 1. Creating a Category
16+
17+
To create a top-level category:
18+
19+
1. Create a directory under `content/en/videos` (e.g., `getting-started`)
20+
2. Add an `_index.md` file inside this directory with the following frontmatter:
21+
22+
```yaml
23+
title: Getting Started # Category text appearing in the /videos category tab and left sidebar
24+
description: >
25+
Getting started videos on Cloud and Kanvas
26+
weight: 2 # Order in which this category appears in the /videos page and left sidebar
27+
icon: bi-rocket-takeoff-fill # Icon for the category (supports Bootstrap icons and local/remote assets)
28+
videoGrid: true # When true, shows all child / nested videos as a grid of cards on this section's index page
29+
# When false, presents a hyperlinked list of videos/sub-sections instead
30+
31+
draft: true # When true, previews this section on local dev server but hides from left sidebar and /videos landing page on published site
32+
```
33+
34+
## 2. Adding Videos to Your Category
35+
36+
There are two approaches for adding videos:
37+
38+
### Approach A: Create a Subcategory with Videos
39+
40+
1. Create a subdirectory under your category (e.g., `getting-started/onboarding`)
41+
2. Add an `_index.md` file with the following frontmatter:
42+
43+
```yaml
44+
title: Onboarding # Subcategory text in the /videos subcategory tab and left sidebar
45+
videoGrid: true # Same functionality as in the category _index.md
46+
weight: 2 # Order in which this subcategory appears
47+
```
48+
49+
3. Create video markdown files (e.g., `video1.md`, `video2.md`) in this subdirectory with the following frontmatter:
50+
51+
```yaml
52+
---
53+
title: "Design Reviews: Adding Comments" # Required: title of the video card/list
54+
description: > # Required: description of the video
55+
Add comments to your designs in Kanvas's Designer Mode to enhance collaboration and streamline design reviews.
56+
videoId: "" # Required: YouTube video ID, example: bb6J--aApk8
57+
videoType: youtube # Required: currently supports "youtube" (support for "local" is present, though currently disabled)
58+
59+
# Categories and tags help match videos with documentation pages by scoring relevance,
60+
# see the guide at bottom to know how
61+
categories: [Designer]
62+
tags: [review, collaboration, comments] # Available as hyperlinked tags in the video card and individual video page
63+
duration: 2:30 # Optional: duration in minutes:seconds format ("min" is automatically added)
64+
---
65+
66+
# the following youtube shortcode is used for individual video page
67+
# Example: {{</* youtube id=bb6J--aApk8 class="yt-embed-container" */>}}
68+
# we can control the styling of resulting iframe and wrapping div by modify style of .yt-embed-container in assets/scss/_videos_project.scss
69+
{{</* youtube id="videoId" class="yt-embed-container" */>}}
70+
```
71+
72+
### Approach B: Add Videos Directly Under a Category
73+
74+
Create video markdown files directly in the category directory with the same frontmatter format shown above. These videos will automatically be assigned to an "ALL" subcategory within the parent category.
75+
76+
## Video and Documentation Page Matching
77+
78+
To display `Related Videos` carousel on documentation pages section pages and individual pages, videos are matched with the docs pages based on shared tags and categories:
79+
80+
- Each matching tag contributes 1 point to the relevance score
81+
- Each matching category contributes 2 points to the relevance score
82+
- Videos with at least one matching tag or category appear in the "Related Videos" carousel
83+
- Videos with higher scores appear first in the carousel
84+
85+
### Example
86+
87+
If a documentation page has:
88+
```yaml
89+
categories: [Designer]
90+
tags: [catalog, publishing]
91+
```
92+
93+
And there are two videos:
94+
95+
**Video A**:
96+
```yaml
97+
categories: [Designer]
98+
tags: [catalog, review]
99+
```
100+
101+
**Video B**:
102+
```yaml
103+
categories: [Designer]
104+
tags: [designs]
105+
```
106+
107+
- **Video A** scores: 2 (category match) + 1 (tag 'catalog') = 3
108+
- **Video B** scores: 2 (category match) + 0 = 2
109+
110+
Video A will appear before Video B in the carousel on the documentation page.
111+
112+
## Example Directory Structure
113+
114+
```yaml
115+
content/en/videos/
116+
└── template-category/ # Top-level section (category)
117+
├── _index.md # Defines the "Template Category" section
118+
└── sub-category/ # Sub-section inside the above category
119+
├── _index.md # Defines the "Sub Category" sub-section
120+
└── video-1.md # file containing video specific data
121+
```
122+
123+
See `content/en/videos/template-category/` for an example of a category with subcategories and videos. It is set to draft and is not published and is intended as a reference for adding videos.

‎content/en/videos/template-category/_index.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Template # the category text on /videos category tab and docs view in left sidebar
3+
description: >
4+
Template Videos for contributing videos docs
5+
weight: 4 # the order in which this category should appear in /videos landing page category tab and and docs view in left sidebar
6+
icon: bi-rocket-takeoff-fill # can use any bootstrap icon or a custom icon
7+
videoGrid: true # show all child / nested videos as grid of cards on the section's index page. for example here the videoGrid: true will show all videos inside getting-started/** as grid of video cards, ommiting of or setting it to false, presents a hyperlinked list of videos / sub-sections
8+
9+
draft: true # can be set to true to hide the section from the left sidebar and /videos landing page on published site, it will still be visible in the local dev server
10+
---

‎content/en/videos/template-category/sub-category/_index.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Sub Category # Subcategory text in the /videos subcategory tab and left sidebar
3+
videoGrid: true # Same functionality as in the category _index.md
4+
weight: 2 # Order in which this subcategory appears
5+
---

‎content/en/videos/template-category/sub-category/video-1.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: "Design Reviews: Adding Comments 1" # required, title of the video card / list
3+
description: > #required, description of the video card
4+
Add comments to your designs in Kanvas's Designer Mode to enhance collaboration and streamline design reviews.
5+
videoId: "bb6J--aApk8" # required, youtube video ID, example: bb6J--aApk8
6+
videoType: youtube # required, we also support "local" for local videos, but it's currenlty disabled.
7+
8+
# categories and tags are used to match videos with documentation pages, by scoring the relevance of the video to the documentation page.
9+
categories: [] # example: [Designer]
10+
tags: [] # example: [review, collaboration, comments] # also available as hyperlinked tags in the video card as well as on individual video page
11+
duration: 2:30 # optional, duration of the video in minutes:seconds format, "min" is automatically appended the duration
12+
---
13+
14+
{{< youtube id=videoId class="youtube-embed-container" >}}
15+
<!-- example: {{< youtube bb6J--aApk8 >}} -->

‎layouts/partials/video-section-index.html

+4
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,11 @@
6060
></video>
6161
{{ else if eq .Params.videoType "youtube" }}
6262
<div class="ratio ratio-16x9 h-100">
63+
{{ if .Params.videoId }}
6364
<img src="https://i.ytimg.com/vi/{{ .Params.videoId }}/maxresdefault.jpg" alt="{{ .Title }}" />
65+
{{ else }}
66+
<img src="/images/video-placeholder-thumbnail.jpg" alt="{{ .Title }}">
67+
{{ end }}
6468
<!-- <iframe
6569
src="https://www.youtube.com/embed/{{ .Params.videoId }}"
6670
title="{{ .Title }}"

0 commit comments

Comments
 (0)