Stackbit Configuration

Relevant source files

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

• stackbit.config.ts
• package.json
• server.js
• about.html
• properties.html
• contact.html
• 404.html
• js/script.js
• css/custom.css

The stackbit.config.ts file is the central integration point for the Stackbit visual editor within this static real estate website. It defines the content structure, models, and the relationship between content files and the static HTML pages. This configuration allows content to be managed in a structured way using JSON files stored in a Git repository, which are then mapped to corresponding pages for rendering.

The primary purpose of this setup is to enable visual editing of a static site. It specifies which parts of the HTML are editable by defining content models. The GitContentSource class indicates that all content is stored directly within the project's Git repository, specifically in the content/ directory. This approach combines the performance and security of a static site with the ease of use of a CMS.

Core Configuration

The configuration is defined using the defineStackbitConfig function from @stackbit/types. It specifies the Stackbit version and contains two main properties: contentSources and siteMap.

// stackbit.config.ts:5-121
export default defineStackbitConfig({
  stackbitVersion: '~0.6.0',
  contentSources: [
    // ... GitContentSource configuration
  ],
  siteMap: ({ documents }) => {
    // ... Site mapping logic
  }
});

• stackbitVersion: Specifies the compatible version of Stackbit, set to ~0.6.0.
• contentSources: An array defining where the content comes from. In this project, a single GitContentSource is used.
• siteMap: A function that maps content documents to the website's URL structure.

Sources: stackbit.config.ts:5-121

Content Source and Models

The project uses GitContentSource to manage content within the same repository as the code. The content is located in the content directory and is structured according to the models defined in the configuration.

Sources: stackbit.config.ts:7-9

The following diagram illustrates the high-level architecture of how Stackbit interacts with the Git repository and the static site.

This diagram shows that Stackbit's editor reads the configuration and content from the Git repository. The content models define the structure of the JSON files, which are linked to the static HTML pages. A local Node.js server is used for development.

Sources: stackbit.config.ts, server.js, about.html:1

Content Models

Two primary content models are defined: Page and Property. These models dictate the structure of the JSON files within the content/pages/ and content/properties/ directories.

The relationship between these models is that a Page can contain a list of properties, but Property is also its own distinct data entity.

This ER diagram shows the Page and Property models and their fields. A Page can optionally contain a list of properties.

Sources: stackbit.config.ts:12-101

Page Model

The Page model represents general-purpose pages of the website, such as "About Us", "Contact", or the "404" page. The content for these pages is stored as JSON files in content/pages/{slug}.json.

Sources: stackbit.config.ts:14-17, about.html:1, contact.html:1, 404.html:1

Field Name	Type	Description	Required
title	string	The page title, used in the <title> tag.	Yes
heroHeading	string	The main heading in the page's hero section.	Yes
heroSubheading	text	The subheading or introductory text in the hero section.	Yes
sections	list	A list of generic content sections, each with a heading and text.	No
properties	list	A list of property cards, used on listing pages.	No
team	list	A list of team members, used on 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 or cards.	No

Sources: stackbit.config.ts:18-81

Property Model

The Property model is a data type, representing individual real estate properties. Each property is stored as a JSON file at content/properties/{slug}.json. This data is used to populate property detail pages and listings.

Sources: stackbit.config.ts:83-86

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

Sources: stackbit.config.ts:87-100

Site Map (siteMap)

The siteMap function is crucial for connecting the abstract content documents to the physical static HTML files. It iterates through all documents from the content source, filters them by model name, and generates a SiteMapEntry for each one. This entry tells Stackbit how to resolve a content object to a URL path and which HTML file to use as its template.

Sources: stackbit.config.ts:104-120

The following flowchart visualizes the logic inside the siteMap function.

This diagram shows how the siteMap function processes documents, distinguishing between 'Page' and 'Property' models to generate the correct URL paths and associate them with the right HTML source files.

Sources: stackbit.config.ts:104-120

Page Mapping

For documents of the Page model, the slug is extracted from the JSON filename (e.g., about.json becomes about). The URL path is then constructed as /{slug}.html, and it's mapped directly to the corresponding HTML file (e.g., about.html).

// stackbit.config.ts:106-114
const pages = documents
  .filter((d) => d.modelName === 'Page')
  .map((d) => {
    const slug = path.basename(String(d.filePath || '').replace(/\.json$/, ''));
    return {
      urlPath: `/${slug}.html`,
      pageSrc: `${slug}.html`,
      pageObjectId: d.id
    } as SiteMapEntry;
  });

This is confirmed by the presence of files like about.html, contact.html, and properties.html in the root directory.

Sources: stackbit.config.ts:106-114, about.html, contact.html, properties.html

Property Mapping

For Property documents, a different logic is applied. While the slug is also extracted from the filename, all property detail pages are rendered using a single template: property-detail-template.html. The URL path is namespaced under /properties/, resulting in URLs like /properties/{slug}.html.

// stackbit.config.ts:116-124
const properties = documents
  .filter((d) => d.modelName === 'Property')
  .map((d) => {
    const slug = path.basename(String(d.filePath || '').replace(/\.json$/, ''));
    return {
      urlPath: `/properties/${slug}.html`,
      pageSrc: `property-detail-template.html`,
      pageObjectId: d.id
    } as SiteMapEntry;
  });

This demonstrates a one-to-many mapping where one template file serves many content documents. Note that property-detail-template.html is not present in the provided file list, implying it might be a file that needs to be created or is handled during a build process not defined in the analyzed files.

Sources: stackbit.config.ts:116-124

Conclusion

The Stackbit configuration in stackbit.config.ts provides a robust framework for managing content on a static website. By defining clear content models (Page, Property) and a logical siteMap, it effectively decouples content from presentation. This allows for a streamlined content editing experience via the Stackbit platform while maintaining the benefits of a static site architecture, which is served by a simple Node.js server for development purposes as seen in server.js. The data-sb-object-id attributes in the HTML files are the final link in this chain, connecting the rendered DOM elements back to their source JSON data.

Sources: stackbit.config.ts, server.js, about.html:1