Mastering SnapApp Docs: A Markdown-First Approach

For developers and content creators, speed and consistency are vital. SnapApp Docs leverages a Markdown-first approach, allowing you to generate documentation and knowledge base articles directly from your local environment using the SnapApp CLI. This workflow bypasses manual UI configuration, letting you focus entirely on your content.

Table of Contents

• Why Use Markdown for SnapApp Docs?
• 1. Structuring Your Documentation File
• The Frontmatter
• The Content
• 2. Installing the SnapApp CLI
• 3. Connecting to Your Instance
• 4. Migrating Content to SnapApp
• Summary of Workflow

Why Use Markdown for SnapApp Docs?

While SnapApp provides a robust Page Builder for complex designs, the Markdown-first approach via CLI is designed for efficiency:

• Focus on Content: Write in plain text without the distraction of design settings.
• Version Control: Store your documentation in Git alongside your code.
• Portability: Easily move content between different SnapApp instances.
• Speed: Use the CLI to upload articles in seconds rather than using a web interface.

1. Structuring Your Documentation File

Every SnapApp Doc file consists of two parts: the Frontmatter (metadata) and the Content (the actual text).

The Frontmatter

Place this YAML block at the very top of your .md file to define how SnapApp categorizes your document:

---
title: "Your Document Title"
author: SnapApp <snapapp@bluevector.ai>
maintainer: "Your Name <email@example.com>"
date: 2024-05-04
description: "A short summary of what this doc covers."
slug: "unique-url-identifier"
tags: "tag1, tag2"
type: "docs"
section: section_name
---

Supported Metadata Fields:

1. title: The headline of your post.
2. author: The creator’s name and contact info.
3. date: Publication or creation date.
4. description: A brief summary for SEO and search results.
5. slug: The URL-friendly version of the title (e.g., getting-started).
6. tags: Keywords used for filtering content.
7. type: The Knowledge Base category in SnapApp (e.g., docs, tips, tutorial).

The Content

Below the frontmatter, write your document using standard Markdown syntax. You can include headings, lists, code blocks, and images.

2. Installing the SnapApp CLI

To push your Markdown files to the SnapApp platform, you must install the SnapApp command-line interface.

Install via Pip:

pip3 install --upgrade --no-cache-dir [https://storage.googleapis.com/snapapp/snapapp-0.1.7-py3-none-any.whl](https://storage.googleapis.com/snapapp/snapapp-0.1.7-py3-none-any.whl)

Verify Installation:

snapapp version

3. Connecting to Your Instance

Before uploading content, you must authenticate your CLI with your SnapApp account.

1. Initialize Configuration: Run snapapp new to set up your environment.
2. Authenticate: Run snapapp login. You will receive a URL to visit in your browser to authorize your device.
3. Test Connection: Run snapapp ping to ensure you are successfully connected.

4. Migrating Content to SnapApp

Once your Markdown file is ready and you are logged in, use the migrate-kb command to upload your document to the SnapApp Knowledge Base.

The Migration Command:

snapapp migrate-kb -f your-filename.md -v v20240504

• -f: Specifies the filename of your markdown document.
• -v: Assigns a version identifier to the upload.

Summary of Workflow

Pro Tip: Ensure that the type specified in your frontmatter exactly matches an existing Knowledge Base category in your SnapApp instance.