Understanding how content URLs are generated by Metalsmith helps prevent build errors. Here's how it works.

Pages in vagov-content

  • Document paths are based on the Markdown file paths.

  • Each Markdown file generates a corresponding directory and index.html file. For example:

    • _education/tools-programs.md/education/tools-programs/index.html

    • _education/tools-programs/index.md/education/tools-programs/index.html

    • _education/work-learn/non-traditional.md_education/work-learn/non-traditional/index.html

Make sure that every collection sub-directory also has a Markdown file that shares its name.

Take the the _employment/job-seekers/ directory as an example. It also has an _employment/job-seekers.md file. Each Markdown file in _employment/job-seekers/ compiles to employment/jobs-seekers/name_of_markdown_file/index.html, while _employment/job-seekers.md itself compiles to employment/job-seekers/index.html.

Failing to take the above step means that you could generate breadcrumbs to pages that do not exist.

Pages in Drupal

In Drupal, URLs are created based off the entityUrl.path property included on each node. Similar to vagov-content pages, an index.html page is appended to that path, so that urls can reference just the path without an html extension.