How do I preview Knative documentation changes locally?

Follow the instructions in the docs contributor guide to set up Material for MkDocs and run the site locally. This lets you see how edits will look on knative.dev before submitting them, ensuring accuracy and formatting.

What templates are available for contributing to Knative docs?

Knative/docs provides structured templates for concepts, procedures, troubleshooting guides, and blog entries. These templates help maintain consistency and are accessible in the 'New content templates' section of the repository.

How does Knative handle older versions of documentation?

Each Knative release has its documentation source stored in separate branches of this repo, with all versions published on knative.dev. This ensures users can access docs for specific releases, starting from version 0.3.

Knative docs vs Kubernetes docs: which is easier to contribute to?

Knative/docs uses Material for MkDocs with specific templates, making it streamlined for its ecosystem, while Kubernetes docs have a different setup. Knative's approach might be simpler if you're familiar with MkDocs, but Kubernetes has broader community resources.

How can I get help with Knative documentation issues?

Ask questions on the #knative-documentation channel in CNCF Slack or join the documentation working group. You can also open issues directly in the GitHub repository for specific problems or feedback.

What tools are used to build the Knative documentation website?

The website is built using Material for MkDocs, a static site generator for technical documentation. Source files are in Markdown and managed in this GitHub repository, with versioning handled through branches.

Open-Awesome

Knative

NOASSERTIONHTML

Source repository and contributor guide for the official Knative documentation website.

Visit Website GitHub

5.1k stars1.3k forks0 contributors

What is Knative?

Knative/docs is the source repository and contributor guide for the official Knative documentation website. It contains all the source files, templates, and instructions for maintaining and contributing to documentation about Knative components, releases, and community resources. The project enables the Knative community to collaboratively create and update technical documentation hosted at knative.dev.

Target Audience

Technical writers, developers, and community contributors who want to create or improve documentation for Knative projects. It's also relevant for users seeking to understand Knative's documentation structure or contribute fixes.

Value Proposition

It provides a centralized, version-controlled repository with clear contribution guidelines and templates, ensuring consistent and high-quality documentation for the Knative ecosystem. The integration with community channels and working groups fosters collaborative documentation efforts.

Overview

User documentation for Knative components.

Use Cases

Best For

Contributing fixes or new content to Knative documentation
Understanding the structure of Knative's versioned documentation
Learning how to use Material for MkDocs for technical documentation
Finding templates for creating concept, procedure, or troubleshooting guides
Joining the Knative documentation working group and community
Previewing documentation changes locally before submission

Not Ideal For

Teams seeking a general-purpose documentation platform independent of a specific project ecosystem
Developers who only need to read documentation without any intent to contribute or modify content
Projects requiring documentation built with tools other than Material for MkDocs or hosted outside GitHub workflows

Pros & Cons

Pros

Versioned Documentation Management

Stores source files for all Knative releases in branches, ensuring historical docs are preserved and accessible on knative.dev, as outlined in the 'Documentation versions for Knative releases' section.

Structured Contribution Templates

Provides specific templates for concepts, procedures, troubleshooting, and blog entries, streamlining consistency and quality, detailed in the 'New content templates' resources.

Local Preview Capability

Allows contributors to run the website locally using Material for MkDocs to preview changes, with instructions linked in the 'Run the website locally' section for easy validation.

Strong Community Integration

Integrates with Knative community resources like Slack channels and working groups, offering direct support and collaboration, referenced in 'Getting help' and community links.

Cons

Toolchain Dependency

Heavily relies on Material for MkDocs for building the website, which can be a barrier for contributors unfamiliar with this static site generator, as setup requires following external guides.

Scattered Contribution Resources

Key guidelines are split between this repo and knative/community, forcing users to navigate multiple sources to contribute effectively, noted in the 'Contributing to docs' section.

Limited Ecosystem Adaptability

The documentation and templates are tailored specifically for Knative projects, making it less useful for documenting other technologies or general-purpose use cases.

Frequently Asked Questions

Related Projects

Vert.x blueprint - Microservice application

Vert.x Blueprint Project - Micro-Shop microservice application

Stars789

Forks298

Last commit7 years ago

Vert.x blueprint - TODO backend

Vert.x Blueprint Project - A reactive todo-backend implementation using Vert.x and various persistence

Stars185

Forks57

Last commit6 years ago

Vert.x blueprint - Job Queue

Vert.x Blueprint Project - Vert.x Kue, a priority task queue powered by Vert.x

Stars146

Forks33

Last commit8 years ago

Vert.x feeds

Feed aggregator using Vert.x 3 (showcase)

Stars131

Forks30