Skip to main content

Core Concepts

Prodcat simplifies the process of creating documentation for your software products by building upon a few core concepts. Understanding these will help you effectively structure your data and customize your generated website.

Software Products​

At the heart of Prodcat is the Software Product. Each software product is an entry in your products.js file that contains all the necessary information to generate a dedicated documentation page for it.

Understanding Software Product Pages​

When Prodcat generates your website, each software product defined in products.js gets its own Markdown page. This page is automatically populated using a Handlebars template (e.g., productPage in prodcat.config.js) and the data provided for that product.

These generated pages are designed to be rich in information, featuring the product's title, description, and any other attributes you define.

Software Product Attributes and products.js​

The products.js file is an array of JavaScript objects, where each object represents a single software product. Key attributes for each product include:

  • name: A human-readable name for the product.
  • id: A unique identifier, used for URL generation.
  • title: The main title for the product's documentation page.
  • description: A detailed overview of the product.
  • category: (Optional) Used for grouping related products.
  • frontMatter: An object containing Docusaurus-specific metadata for the generated Markdown page (e.g., sidebar_label, description for SEO).

Example: products.js with Multiple Products

Consider the following products.js file:

// products.js
module.exports = [
  {
    name: 'Prodcat CLI Tool',
    id: 'prodcat-cli',
    title: 'Prodcat Command Line Interface',
    description: 'The main tool for generating and managing Prodcat websites.',
    category: 'Development Tools',
    frontMatter: {
      description: 'The CLI tool for Prodcat.',
      summary: 'Command line utility for Prodcat.',
      sidebar_label: 'CLI Tool',
    },
  },
  {
    name: 'Prodcat Dashboard',
    id: 'prodcat-dashboard',
    title: 'Prodcat Web Dashboard',
    description: 'A web-based interface to manage your product documentation.',
    category: 'Web Applications',
    frontMatter: {
      description: 'Web dashboard for Prodcat.',
      summary: 'User-friendly web interface.',
      sidebar_label: 'Dashboard',
    },
  },
  {
    name: 'Prodcat Templates',
    id: 'prodcat-templates',
    title: 'Customizable Prodcat Templates',
    description: 'Extend Prodcat\'s appearance with custom Handlebars templates.',
    category: 'Development Tools',
    frontMatter: {
      description: 'Custom templates for Prodcat.',
      summary: 'Handlebars templates for customization.',
      sidebar_label: 'Templates',
    },
  },
];

In this example:

  • Each object represents a distinct software product.
  • id is used to create unique URLs (e.g., /docs/prodcat-cli).
  • category helps group products, which can be leveraged in templates for navigation or display.
  • frontMatter properties like sidebar_label determine how the product appears in the Docusaurus sidebar.

Categories​

Categories in Prodcat serve as a logical grouping mechanism for your software products. While Prodcat itself doesn't enforce strict category-based routing, the category attribute in your products.js can be effectively used within your Handlebars templates to organize and display products.

Browsing by Category​

By defining a category for each product, you can create dynamic sections or filters on your landing page (generated by landingPage.md.hbs) or other custom pages. For example, you could list all "Development Tools" together, separate from "Web Applications."

Understanding Category Pages (Template-driven)​

Prodcat does not automatically generate dedicated "category pages" out-of-the-box. Instead, the concept of a category page is realized by how you design your landingPage template or other custom templates. You can iterate through your products, group them by their category attribute, and render them accordingly.

Example: Leveraging Categories in a Template

A Handlebars template (e.g., landing-page.md.hbs) might contain logic like this to group products by category:

{{!-- landing-page.md.hbs excerpt --}}
{{#each categories as |categoryName productsInThisCategory|}}
  <h2>{{categoryName}}</h2>
  <ul>
    {{#each productsInThisCategory as |product|}}
      <li>
        <a href="/docs/{{product.id}}">{{product.title}}</a>
        <p>{{product.summary}}</p>
      </li>
    {{/each}}
  </ul>
{{/each}}

This template snippet demonstrates how productsInThisCategory (derived from the category attribute in products.js) can be used to dynamically create category-based listings on your landing page.

(Placeholder for future content on search functionality, filters, and operators.)