FPM Sitemap

FPM

Home

How to use Google Font

FPM Sitemap

“FPM Sitemap” is the name of a structure we recommend for sites. It is optional, you can create any sitemap you want for your sites. FPM has built in support for FPM Sitemap.

The Structure

A site should have “sections” on top level. Each section should ideally be listed in the header of the site.

Each section should have one or more sub-sections. Sub-section should be listed as second level navigation in the header of the site. Each sub-section has one or more documents organised in a “table of content”, and TOC should be shown on the left.

In the UI we also have “Section/Sub Section” Nav. It automatically will show the section name and sub-section name.

Sitemap “Language”

FPM comes with a variable called “sitemap”, which contains the sitemap structure and later this structure get parses. The sitemap should be included in FPM.ftd file.

Sitemap Example

# Section: /section/url/
nav-title: Optional Longer Section

# If Section: Has A Colon In The Name
url: sectionURL

## Sub Section: /sub/url/
nav-title: Longer Sub Section

## If Sub Section: Has A Colon In The Name
url: whatever

- ToC Item: toc/
  nav-title: Shorter title

# Section: /section/url/
nav-title: Optional Longer Section

# If Section: Has A Colon In The Name
url: sectionURL

## Sub Section: /sub/url/
nav-title: Longer Sub Section

## If Sub Section: Has A Colon In The Name
url: whatever

- ToC Item: toc/
  nav-title: Shorter title

Note: The URLs in sitemap start with slash, but we remove the first slash if --base is not equal to /. We support --base because some projects may deploy FPM package on a base URL eg, foo.com/bar/, so all reference to /x/ is actually a reference to foo.com/bar/x/. In this case we also convert / to index.html.

Sitemap $processor$

We have $processor$ called get-sitemap, which can be used to get sitemap data:

-- fpm.sitemap-data sitemap:
$processor$: get-sitemap

-- fpm.sitemap-data sitemap:
$processor$: get-sitemap

Consider a package contains the following sitemap

In FPM.ftd

-- fpm.sitemap:

# Section Title: /


## Subsection Title: /

- Toc Title: /
- Toc Title 1: /foo/
  - Bar Title: /bar/


## Subsection Title 2: subsection2/

- Other Toc Title: subsection2/foo/



# Second Section Title: section/

## Second Subsection Title: second-subsection/

- Second Toc Title: second-toc/

-- fpm.sitemap:

# Section Title: /


## Subsection Title: /

- Toc Title: /
- Toc Title 1: /foo/
  - Bar Title: /bar/


## Subsection Title 2: subsection2/

- Other Toc Title: subsection2/foo/



# Second Section Title: section/

## Second Subsection Title: second-subsection/

- Second Toc Title: second-toc/

Now, for the get-sitemap processor in the document with id bar/ would return the value

{
  "sitemap": {
    "sections": [
      {
        "title": "Section Title",
        "url": "/",
        "is-active": true,
        "children": []
      }
    ],
    "subsections": [
      {
        "title": "Subsection Title",
        "url": "/",
        "is-active": true,
        "children": []
      },
      {
        "title": "Subsection Title 2",
        "url": "subsection2",
        "is-active": false,
        "children": []
      }
    ],
    "toc": [
      {
        "title": "Toc Title",
        "url": "",
        "is-active": false,
        "children": []
      },
      {
        "title": "Toc Title 1",
        "url": "foo/",
        "is-active": true,
        "children": [
          {
            "title": "Bar Title",
            "url": "bar/",
            "is-active": true,
            "children": []
          }
        ]
      }
    ]
  }
}

{
  "sitemap": {
    "sections": [
      {
        "title": "Section Title",
        "url": "/",
        "is-active": true,
        "children": []
      }
    ],
    "subsections": [
      {
        "title": "Subsection Title",
        "url": "/",
        "is-active": true,
        "children": []
      },
      {
        "title": "Subsection Title 2",
        "url": "subsection2",
        "is-active": false,
        "children": []
      }
    ],
    "toc": [
      {
        "title": "Toc Title",
        "url": "",
        "is-active": false,
        "children": []
      },
      {
        "title": "Toc Title 1",
        "url": "foo/",
        "is-active": true,
        "children": [
          {
            "title": "Bar Title",
            "url": "bar/",
            "is-active": true,
            "children": []
          }
        ]
      }
    ]
  }
}

Missing Sub Section

If a TOC comes directly in a section the section would have a single anonymous sub-section, and this sub-section would not be shown in UI. In UI people will just see the section header and toc on left, no sub-section line.

# Section Title: section/

- Toc 1: toc/
  - Toc 2: toc2/

# Section Title: section/

- Toc 1: toc/
  - Toc 2: toc2/

FPM Build Behaviour

If a document is not part of sitemap, it will be built as is built right now. All documents that are part of sitemap are built in a special way.

FPM build will first parse the sitemap and build all the URLs that are not part of it, and then in another pass build all the ones that are in it.

A document can appear in multiple places in sitemap, in that case FPM builds one HTML file for each time a ftd document appears in sitemap.

Note: A document can appear only once in a single TOC?

Canonical URL

If a ftd document appears multiple times in sitemap, one of them would be the canonical, the “main” URL.

Consider the following example:

Suppose foo.ftd has to be appeared more than once in the sitemap. The sitemap can include this document as foo/, this is the “main” URL. The other way to include it is by passing url something like this. foo/-/<something>/. The -/ is the pointer to get the document. Anything preceding -/ would be the document id. The generated html of this document will include the canonical url pointing to foo/.

Key Value Data in Sitemap

Document can use get-data processor to get value of any key specified in the sitemap. Since a document would get rendered once for each occurrence of the document in the sitemap, each occurrence can have different data and the occurrence specific data would be returned by get-data.

The key value pair supports inheritance. This means that the key-value pair data presents in section get passed to it’s subsection and TOCs. Similarly, subsection key value data get passed to TOCs. And also the parent TOC-item’s key value data get passed to its children TOC.

# name: section/url/
key1: value1
key2: value2

## sub name: subsection/url/
key3: value3

- toc/url/
  key4: value4
  - childtoc/url/
    key5: value5

# name: section/url/
key1: value1
key2: value2

## sub name: subsection/url/
key3: value3

- toc/url/
  key4: value4
  - childtoc/url/
    key5: value5

In the above example, the section/url/ section have two key value data key1: value1 and key2: value2 The subsection/url/ subsection have three key value data where two are inherited from section. i.e. key1: value1, key2: value2 and key3: value3 The toc/url/ toc item have four key value data, where three are inherited from section and subsection. i.e. key1: value1, key2: value2, key3: value3 and key4: value4 The childtoc/url/ toc item have five key value data, where four are inherited from section, subsection and it’s parent TOC. i.e. key1: value1, key2: value2, key3: value3, key4: value4 and key5: value5

Variable can be changed based on key value data

Using the get-data, the title can be different:

-- boolean show-dev-info:
$processor$: get-data

-- string page-title: The Normal Title

-- page-title: The Dev Title
if: $show-dev-info

-- ft.h0: $page-title

-- boolean show-dev-info:
$processor$: get-data

-- string page-title: The Normal Title

-- page-title: The Dev Title
if: $show-dev-info

-- ft.h0: $page-title

sitemap

-- fpm.sitemap:

# Overview

- foo/

# Development

- foo/-/1
  show-dev-info: true

-- fpm.sitemap:

# Overview

- foo/

# Development

- foo/-/1
  show-dev-info: true