Core Concepts of SmartGen Docs

To effectively utilize SmartGen Docs, it is beneficial to understand the fundamental concepts that underpin its design and operation. This section clarifies key terminology and principles, providing a solid foundation for building and managing your documentation projects.

1. Markdown-Centric Documentation

At its core, SmartGen Docs is built around Markdown. Markdown is a lightweight markup language that allows you to write using an easy-to-read, easy-to-write plain text format, which then converts to structurally valid HTML. This approach offers several advantages:

• Simplicity: Focus on content creation without the complexities of rich text editors or intricate HTML.
• Portability: Markdown files are plain text, making them highly portable and compatible with various tools and version control systems.
• Readability: Even in its raw form, Markdown is designed to be human-readable, facilitating collaboration and review.

SmartGen Docs extends standard Markdown with features like fenced code blocks, tables, and task lists, enhancing its capabilities for technical documentation.

2. Static Site Generation (SSG)

SmartGen Docs operates as a Static Site Generator (SSG). This means it takes your source content (Markdown files) and templates, processes them, and outputs a complete set of static HTML, CSS, and JavaScript files. These files are then served directly to users by a web server, without any server-side processing for each request.

Key characteristics of SSGs like SmartGen Docs include:

• Pre-rendered Content: All pages are generated once at build time, not on every user request.
• Performance: Static files are delivered quickly, leading to faster load times and a better user experience.
• Security: Reduced attack surface as there are no databases or server-side scripting vulnerabilities.
• Scalability: Easily handles high traffic volumes as serving static files is resource-efficient.
• Deployment Simplicity: The output is a collection of files that can be hosted on any static web server or CDN.

For more information on deployment, refer to the Deployment Guide.

3. Configuration via smartgen.yml

The behavior and structure of your SmartGen Docs site are primarily controlled by the smartgen.yml configuration file. This YAML-formatted file acts as the central blueprint for your documentation project.

It defines critical aspects such as:

• Site Metadata: site_name, site_url, site_author, site_description.
• Navigation Structure: The nav section dictates the hierarchy and order of your documentation pages, forming the main menu.
• Theming: Specifies the visual theme and allows for customization of colors and fonts.

Understanding and managing smartgen.yml is essential for tailoring your documentation to your specific needs. See the Configuration Guide for a detailed breakdown.

4. The docs/ Directory

The docs/ directory is the designated location for all your Markdown source files. This directory is where you organize your content, creating subdirectories to reflect the logical structure of your documentation. Each .md file within docs/ corresponds to a page in your final static site.

• Content Source: All textual content for your documentation originates from Markdown files within this directory.
• Hierarchical Organization: Subdirectories allow for logical grouping of related topics, which directly influences the navigation structure.
• index.md: Each main section or subdirectory typically contains an index.md file, serving as the overview or landing page for that section.

Refer to the Folder Structure Guide for best practices on organizing your docs/ directory.

5. The site/ Directory

The site/ directory is the output location for your generated static website. After running the smartgen-docs build command, all the processed HTML files, along with CSS, JavaScript, and other static assets, are placed here.

• Deployment Ready: The contents of this directory are what you upload to your web server for public access.
• Auto-Generated: This directory is entirely generated by SmartGen Docs and should not be manually edited, as changes will be overwritten during subsequent builds.

6. Path Resolution

SmartGen Docs employs a sophisticated Path Resolver mechanism to ensure that all internal links (e.g., links between Markdown pages) and references to static assets (e.g., images, CSS) are correctly resolved in the generated HTML. This is particularly important for nested directory structures, where relative paths can become complex.

• Dynamic Linking: The system automatically adjusts paths based on the location of the current page, ensuring that links always point to the correct destination.
• Consistent Navigation: Contributes to a seamless user experience by preventing broken links.

These core concepts work in concert to provide a robust, efficient, and user-friendly platform for creating and maintaining high-quality project documentation with SmartGen Docs.