Add "Blogs" to contribute/docs/source-file-structure

[StackScribe]

Summary

Need to add a subsection about "Blogs" to contribute/docs/source-file-structure.md to explain how blogs fit into the documentation infrastructure.

Information needed

• What determines the published structure of the "Blogs" tab? mkdocs.yml references docs/blogs/index.md but does not seem to list the individual blog files
• For the purposes of links/xrefs, are blogs part of NAV? So relative or full URL for target-link?
• What goes into the Archives section and where are those located? We have entries for 2024 and 2023 but they currently seem to have identical content. Is this section generated manually or automatically? Can anyone modify it or only admins?
• Categories section seems to sort blogs by topical group. Where is the file that controls what is in each category? How does one add a file to an existing category? How does one create a new category?
• Should the blog/index.md file explain a bit about the structure of the blogs area and link to this new document for instructions to create a new blog or blog category?
• Anything else contributors should know?

DoD

• "Blogs" page in contribute/docs/
  • Blogs are managed by the blog plugin from mkdocs-material which automatically manages the blog infrastructure.
  • Blogs are authored in markdown and built using the same tools and github practices as other documentation
  • Blogs are considered part of the NAV path for cross-referencing, so use relative paths to xref the Keptn documentation and full URLs to reference pages outside the Keptn docs NAV path
• How to create a new blog post
  • Add your information to the blogs/.authors.yml file
  • Add the GitHub user id you used to the .github/actions/spelling/expect.txt file
  • Create a PR that adds the .md file for your blog to the docs/blogs directory. Describe the metadata fields that must be created
• How to include sample YAML files and other assets in a blog post

[mowies]

Some initial info: We are using the blog plugin from mkdocs-material which handles everthing around the blog automatically. We just need to provide blog posts with some optional metadata.

• What determines the published structure of the "Blogs" tab? mkdocs.yml references docs/blogs/index.md but does not seem to list the individual blog files

the blog plugin handles the whole structure

• For the purposes of links/xrefs, are blogs part of NAV? So relative or full URL for target-link?

same as for the rest of the docs, you need to use relative paths to the markdown files and the blog plugin will handle the rest (source)

• What goes into the Archives section and where are those located? We have entries for 2024 and 2023 but they currently seem to have identical content. Is this section generated manually or automatically? Can anyone modify it or only admins?

This is handled automatically by the blog plugin. The year sections show posts published in that year. The blog plugin uses the date field in the frontmatter of each blogpost markdown file for this.

• Categories section seems to sort blogs by topical group. Where is the file that controls what is in each category? How does one add a file to an existing category? How does one create a new category?

This is also auto-generated by the blog plugin. Authors can use arbitrary categories for posts that are defined in the frontmatter of the post. The plugin will then use those categories for the auto-generated page.

• Should the blog/index.md file explain a bit about the structure of the blogs area and link to this new document for instructions to create a new blog or blog category?

The blog plugin generates the index page automatically, so there is no way of adding extra content to the index file. It's just there so that the blog plugin knows what file location to use for the blog.