Architecture

Key Files

Any Marque site has three key files that control the site's behaviour and structure:

marque.toml

marque.toml is the default configuration file for any Marque site. It contains settings that apply to every page. It defines parameters like the site's title, theme, layout, and more. You can find out more about this in the frontmatter documentation.

navigation.mq

The navigation.mq file defines the structure and order of the site's pages. It controls the site's navigation hierarchy, including how pages are grouped and nested in the menu. You can find out more about this in the navigation documentation.

common.css

common.css is the shared visual baseline for the site. It contains the default styling for markdown elements, built-in directives, shared chrome such as search and page navigation, and the pieces every theme builds on top of. You usually should not edit this file directly when making a custom look. Instead, create a new theme in themes/ and override what you need there. You can find out more about this in the themes documentation.

Key Folders

Marque projects separate features into different folders. This makes it easier for both casual users and developers to make their site without understanding the entire codebase.

Marque separates the website into 5 distinct folders:

pages/

The pages folder is the most important folder in the project. This is where you write the content of your site, in Marque (.mq). Each file in this folder corresponds to a page on the site. Marque files are markdown files that can use Marque's custom directives to create enhanced elements and layouts.

themes/

The themes folder contains your site's visual styling. New custom themes live at the root of themes/ as small token-first CSS files, while bundled legacy themes live in themes/legacy/. A theme is a .css file that layers on top of common.css to apply custom fonts, colors, and shapes to elements of your site. Find out more about this in the themes documentation.

layouts/

The layouts folder contains two different things: They contain the core index.html file that defines the structure of each page on the site, along with additions that accompany it in layouts/partials/, and custom javascript such as index.js that makes the site interactive. The second thing they contain is custom layouts, defining how content is arranged on the page. Notably, sidebar.css and topnav.css define the structure of the navigation bar's behaviour and positioning on the site. You can find out more about this in the layouts documentation.

directives/

The directives folder is where Marque's custom directives are defined. Directives are add-ons that enhance classic markdown, allowing you to create elements and layouts that aren't possible with markdown alone, such as side-by-side columns, buttons and more. If you're a beginner, you won't need to touch this folder, but experienced web developers can edit or create their own directives to expand Marque's functionality. The directives are documented in the directives documentation.

static/

Finally, the static folder contains assets you want to use on your site, such as images, documents, icons and more. You can link to these assets in your pages and they will be copied over to the output folder when you build the site. For more on this, see the assets documentation.

dist/

Dist isn't a folder that exists in the project structure by default, it's actually the output folder that Marque generates when you build your site. It contains the static site that you can deploy to the web (or run locally!). You shouldn't edit this folder, as it will be overwritten whenever you edit and build your Marque site.

What to edit first

To start making your first modification to the site, the best place to start is inside the key files: marque.toml and navigation.mq. These files will allow you to make the most impactful changes to the site with the least amount of effort, and will help you understand how Marque works.