Stackbit Overview

Relevant source files

The following files were used as context for generating this wiki page:

• stackbit.config.ts
• package.json
• server.js
• about.html
• contact.html
• properties.html
• 404.html

Stackbit is integrated into this project as a headless Content Management System (CMS) that uses the Git repository as its data source. It allows for visual editing of the static HTML website by defining content models that correspond to JSON files stored in the content/ directory. The configuration file, stackbit.config.ts, is the central point for defining the content structure, how data maps to pages, and enabling Stackbit's visual editing capabilities.

The overall architecture is a simple static site served by a basic Node.js server, with Stackbit providing the content management layer. This allows non-developers to update website content like page text, property listings, and team members by modifying structured JSON files through the Stackbit user interface.

Core Configuration

The entire Stackbit integration is defined within stackbit.config.ts. It uses the defineStackbitConfig function to export the site's configuration.

// stackbit.config.ts:4-5
export default defineStackbitConfig({
  stackbitVersion: '~0.6.0',
  // ...
});

The configuration specifies the Stackbit version and defines the content sources, data models, and the site map.

Sources: stackbit.config.ts:4-5

Content Source: Git

The project uses GitContentSource to manage content directly within the Git repository. This means all editable content is stored as files (in this case, JSON) and version-controlled alongside the application code.

The configuration for the content source is as follows:

• name: 'content' - A unique identifier for this source.
• rootPath: __dirname - The root of the project directory.
• contentDirs: ['content'] - Specifies that editable content is located within the content directory.
• models: An array defining the structure of the content.

Sources: stackbit.config.ts:7-11

This diagram illustrates the relationship between the Stackbit configuration, the file system, and the Git repository.

Content Models

Two primary content models are defined: Page and Property. These models dictate the schema for the JSON files stored in the content/ directory.

Page Model

The Page model is a page type, meaning it represents a routable page on the website. These pages are stored as JSON files in content/pages/.

• type: page
• filePath: content/pages/{slug}.json
• urlPath: /{slug}

The fields for the Page model are designed to be flexible, accommodating various types of content sections.

Field Name	Type	Description	Required
title	string	The title of the page, often used in the <title> tag.	No
heroHeading	string	Main heading for the hero section.	No
heroSubheading	text	Subheading or paragraph for the hero section.	No
sections	list	A list of generic content sections, each with a heading and text.	No
properties	list	A list of property cards for listing pages.	No
team	list	A list of team members for pages like "About Us".	No
faqs	list	A list of frequently asked questions, each with a question and answer.	No
blogPosts	list	A list of blog post summaries for blog listing pages.	No

Sources: stackbit.config.ts:13-98

Property Model

The Property model is a data type, representing a data object that can be referenced or used to generate pages. These are stored in content/properties/.

• type: data
• filePath: content/properties/{slug}.json

This model defines the structure for an individual real estate property.

Field Name	Type	Description	Required
title	string	The name or title of the property.	No
price	string	The listing price.	No
address	string	The property's address.	No
description	text	A detailed description of the property.	No
image	string	URL or path to the main property image.	No
url	string	The URL for the property's detail page.	No
bedrooms	number	Number of bedrooms.	No
bathrooms	number	Number of bathrooms.	No
area	number	The area of the property (e.g., in square meters).	No
floors	number	Number of floors.	No

Sources: stackbit.config.ts:100-116

Model Relationship Diagram

The following ER diagram shows the defined models and their fields.

Site Map Generation

The siteMap function is crucial for linking the content documents (JSON files) to the static HTML files that are served to the user. It iterates through all documents from the content source and creates a mapping for each one.

The process is as follows:

1. It receives all documents managed by Stackbit.
2. It filters for documents with modelName === 'Page'. For each, it creates a SiteMapEntry that maps the JSON file's slug to a corresponding .html file (e.g., about.json -> /about.html).
3. It filters for documents with modelName === 'Property'. For each, it creates a SiteMapEntry that maps the property to a generic template (property-detail-template.html) under a specific URL path (e.g., my-property.json -> /properties/my-property.html).
4. It combines and returns all entries.

Sources: stackbit.config.ts:120-144

This flowchart visualizes the logic of the siteMap function.

HTML Integration for Visual Editing

Stackbit enables visual editing by linking elements in the static HTML files back to the content source. This is achieved using special data-sb-* attributes.

• data-sb-object-id: This attribute is placed on the <html> tag of a page. Its value is the ID of the corresponding JSON document in the content/ directory. This tells Stackbit which content object the entire page is associated with.

  <!-- about.html:1 -->
  <!DOCTYPE html><html lang="lv" data-sb-object-id="content/pages/about.json">
  

  Sources: about.html:1, contact.html:1, properties.html:1, 404.html:1

• data-sb-field-path: This attribute is placed on individual HTML elements (like <h1>, <p>, <img>). Its value is a path to a specific field within the JSON object. This allows Stackbit to highlight the element in the visual editor and update the correct field when a user makes a change.

  <!-- about.html:162 -->
  <h1 class="display" style="max-width: 700px;" data-i18n="about_us" data-sb-field-path="heroHeading">Par mums</h1>
  
  <!-- about.html:166 -->
  <p data-i18n="vandore_heritage_began_with_a_conversation_not_about_how_to_sell_more_but_about_how_to_do_things_right" data-sb-field-path="heroSubheading">Vandore Heritage sākās ar sarunu - nevis par to, kā pārdot vairāk, bet gan par to, kā rīkoties pareizi.</p>
  

  Sources: about.html:162-166, contact.html:158-162

This integration allows a content editor to click directly on text or images in the live site preview within Stackbit and edit the content, with the changes being saved back to the corresponding JSON file in the Git repository.

Serving the Static Site

The project includes a simple Node.js server (server.js) to serve the static files locally. The package.json file defines dev and start scripts that run this server.

// package.json:5-7
"scripts": {
  "dev": "node server.js",
  "start": "node server.js"
},

The server handles requests for various file types (.html, .css, .js, etc.) and serves a custom 404.html page if a requested file is not found. This provides the runtime environment for the static website that Stackbit manages.

Sources: package.json:5-7, server.js