DOCSEARCHbyAlgolia
Submit Docs

Front Matter CMS for Visual Studio Code

repository·main·Indexed 25 days ago

https://github.com/estruyf/vscode-front-matter

A headless CMS that runs within Visual Studio Code, providing content, media, and data management for static site generators such as Hugo, Jekyll, Docusaurus, NextJs, and Gatsby. Features include a dedicated dashboard, SEO tools, multilingual support, taxonomy management, and the ability to generate article slugs and manage timestamps directly within the editor.

Tokens
7.5K
Snippets
7
Records
58
Agent score
82%

What's inside Front Matter CMS

  1. What is Front Matter CMS?

    main

    Front Matter is a headless CMS that runs directly within Visual Studio Code. It provides content, data, and media management capabilities while maintaining the flexibility of your chosen static site generator (SSG).

    Key Features:

    • Content Management: Search, filter, sort, and create new content.
    • Data & Media Management: Dedicated dashboards for managing data files/folders and media assets.
    • SSG Support: Works with Hugo, Jekyll, Hexo, NextJs, Gatsby, and more.
    • Preview: View your site or content directly within VS Code.
    • SEO Tools: Built-in SEO checks for titles, descriptions, and keywords.
    • Multilingual Support: Manage content in multiple languages (introduced in v10).
    • Taxonomy Management: Dashboard to manage tags, categories, and custom taxonomies.
    • Snippets: Support for content snippets.
    • Extensibility: Ability to extend functionality to meet specific use cases.

  2. Understand the extension project structure

    main

    A standard VS Code extension project contains these key files:

    • package.json: The manifest file. It is used to declare extension metadata, contribution points (like commands), and activation events. VS Code reads this to show commands in the command palette without needing to load the full plugin first.
    • src/extension.ts: The main entry point. It must export an activate function, which is called when the extension is activated. This is where you typically call registerCommand to bind implementation logic to commands declared in package.json.

  3. Configure Telemetry settings

    main
    Front Matter CMS only uses telemetry for application crashes. It respects the standard VS Code telemetry.enableTelemetry setting. For crash reports within webviews, the extension uses Sentry to help identify and fix issues. The user's IP address is not collected.

  4. Install Front Matter CMS

    main

    You can install the Front Matter extension via the VS Code Marketplace or using the extension CLI.

    To install the stable version via the CLI, use: ext install eliostruyf.vscode-front-matter

    Alternatively, search for "Front Matter" in the VS Code Marketplace.

    ext install eliostruyf.vscode-front-matter

  5. Initialize Front Matter for your project

    main

    After installing Front Matter, you must initialize your project using the Front Matter dashboard. The dashboard provides a guided workflow to set up your environment.

    When you open the dashboard for the first time in a new project, you will need to complete these three steps:

    1. Project initialization: Set up the core Front Matter project structure.
    2. Content folders registration: Specify which folders in your workspace contain your content files.
    3. Framework initialization: Configure the specific framework (e.g., Astro, Next.js, Hugo, etc.) that your project uses.

  6. Install the Front Matter BETA version

    main

    If you want to test experimental features, you can install the beta version. Note that you must first uninstall the stable version of Front Matter before installing the beta.

    To install the beta version via the CLI, use: ext install eliostruyf.vscode-front-matter-beta

    Alternatively, search for "Front Matter BETA" in the VS Code Marketplace.

    ext install eliostruyf.vscode-front-matter-beta

  7. Run and debug your VS Code extension

    main

    To test your extension in a development environment:

    1. Launch the extension: Press F5 to open a new VS Code window (Extension Development Host) with your extension loaded.
    2. Execute commands: Open the command palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and type the command name (e.g., Hello World) to trigger your extension's logic.
    3. Debug: Set breakpoints directly in src/extension.ts. When the command is executed, the execution will pause at your breakpoint, allowing you to inspect variables in the Debug Console.
    4. Relaunch: After making code changes in src/extension.ts, use the debug toolbar to relaunch or reload the window (Ctrl+R or Cmd+R on Mac) to apply changes.

  8. Get support for Front Matter CMS

    main

    If you need assistance with Front Matter CMS, you can use the following channels:

    • Questions and Experiences: Use GitHub Discussions to ask general questions or share how you use the tool.
    • Bugs and Feature Requests: Open a GitHub Issue if you encounter a technical problem or want to suggest a new feature.
    • Community Chat: Join the Discord server to ask questions and interact with the community in real-time.

  9. Run extension tests

    main

    To run the automated test suite:

    1. Open the Debug Viewlet (Ctrl+Shift+D or Cmd+Shift+D on Mac).
    2. Select Extension Tests from the launch configuration dropdown.
    3. Press F5 to run the tests in a new window.
    4. View test results in the Debug Console.

    Creating new tests:

    • Add new test files inside the test/suite folder.
    • Ensure files follow the naming pattern **.test.ts so the test runner detects them.
    • You can use subfolders within test to organize your test suite.

  10. How i18n translation and file creation works

    main

    The i18n system manages multi-language content by mapping source files to target locale files based on I18nConfig settings.

    Workflow

    1. Detection: The system identifies the sourceLocale of the current file and looks up available targetLocales from the project settings.
    2. Front Matter Update: When creating a new translation, the system updates the front matter to ensure compatibility with the target locale. This includes processing image fields to ensure relative paths are correctly adjusted for the new directory structure.
    3. Translation: If configured, the system uses the Translations service (DeepL) to translate the following fields from the source to the target:
      • The field identified as the Title
      • The field identified as the Description
      • The main Content
    4. File Placement: New files are placed in directories determined by the path property in your I18nConfig, relative to the localeSourcePath of the page folder.

  11. Automatic Front Matter Validation and SEO Checks

    main

    The extension automatically monitors your active editor to provide real-time feedback on your front matter. When a supported file is active, the StatusListener performs the following tasks:

    1. SEO Length Validation: Checks the length of your title and description fields against configured limits (SETTING_SEO_TITLE_LENGTH and SETTING_SEO_DESCRIPTION_LENGTH).
    2. Required Fields Check: Identifies missing fields required by your content type and reports them as errors.
    3. Schema Validation: If enabled via SETTING_VALIDATION_ENABLED, it validates the front matter data against the defined schema for the detected content type.
    4. Metadata Sync: Automatically pushes front matter metadata to the active Panel WebView if it is visible.

    Errors and warnings are surfaced directly in the editor via VS Code Diagnostics (squiggles) and, in the case of missing required fields, via notifications.

  12. How the Preview URL (slug) is generated

    main

    The preview system generates a URL (slug) for each markdown file to allow viewing the rendered content via a local server. The generation process follows this hierarchy:

    1. Slug Extraction: It first looks for a slug field in the article's front matter. If not found, it uses the file name.
    2. Pathname Resolution: It determines the base path using:
      • The pathname setting.
      • The previewPath defined for the specific ContentFolder.
      • The previewPath defined for the ContentType.
    3. Placeholder Processing: The pathname is processed to resolve various placeholders:
      • Time placeholders: e.g., date formats.
      • Custom placeholders: Defined via ArticleHelper.processCustomPlaceholders.
      • Path placeholders: {{pathToken.<integer>}} based on the file's relative path.
      • i18n placeholders: For localized content.
      • Front Matter placeholders: {{fm.<field>}} using values from the article's front matter.
    4. Final Assembly: The processed pathname and slug are joined, and a trailing slash is added if configured. Special handling is applied to index or _index files to ensure clean URLs.