Split pages

This page demonstrates the split page pattern and provides steps on how to implement it on a site.

To improve internal developer experience, the pattern splits a longer page into multiple markdown files (also known as markdown partial files) and then imports the markdown files into a single page (also known as the main page).

This split page pattern is used by the following pages:

• API documentation
• Studio manual reference
• Accounts pricing page
• Vector Tiles Specification

How to use split pages

Before you begin using this pattern, read about its limitations to make sure it's the right option for your site.

1. Create the main page

The main page is where you will combine all the partial markdown files.

1. Create an index.js file, this is the main page. It must be a JavaScript file so that the sidebar scroll spy will work correctly.
2. In the frontmatter of the main page:
   • Add splitPages: true to the frontmatter.
   • Add order to choose the order in which it will appear in the NavgiationAccordion.
   • Set hideFeedback: true (usually). If the partial files will have feedback enabled, you'll want to disable the feedback from also appearing at the bottom of the page.
3. Once created, import each partial file in the main page.
4. Import the splitPages function to override the page's headings. (Depending on your set-up, this step may happen in the site's page-shell instead.)

Example

/*---
title: Split pages
description: This is the first section
splitPages: true
order: 3
layout: page
contentType: API
---*/
 
import React from 'react';
 
// Import each markdown file.
import Intro from './sections/intro.md';
import HowTo from './sections/how-to.md';
import Limitations from './sections/limitations.md';
import TagDebugger from './sections/tag-debugger.md';
import PageShell from '../../../components/page-shell';
 
// Import splitPage function
import splitPages from '@mapbox/batfish/data/split-pages'; // eslint-disable-line
 
export default class Page extends React.PureComponent {
render() {
const { location } = this.props;
// Override the combines headings in the sidebar
const headings = splitPages[location.pathname].headings;
return (
<PageShell headings={headings} {...this.props}>
<Intro {...this.props} />
<HowTo {...this.props} />
<Limitations {...this.props} />
<TagDebugger {...this.props} />
</PageShell>
);
}
}

2. Create the split pages

1. Create a new directory, sections/, in the same folder as the index.js you created in the previous step.
2. In the sections/ directory, compose your markdown files.
3. In each markdown file:
   • Add splitPage: true to the frontmatter.
   • Add order: to chose the order in which each section (or partial markdown file) will appear on the main page - this is necessary in generating the headings. You will need to make sure this is the same order as the imported partial files in the main page.

Example

---
title: Introduction to split pages
description: An introduction to use split pages.
order: 1
splitPage: true
hideFeedback: true
products:
- Documentation
contentType: guide
---
 
This page demonstrates the split page pattern and provides steps on how to implement it on a site.
 
To improve internal developer experience, the pattern splits a longer page into multiple markdown files (also known as markdown partial files) and then imports the markdown files into a single page (also known as the main page).
 
This split page pattern is used by the following pages:
 
- [API documentation](https://docs.mapbox.com/api/maps/)
- [Studio manual reference](https://docs.mapbox.com/studio-manual/reference/)
- [Accounts pricing page](https://docs.mapbox.com/accounts/overview/pricing/)
- [Vector Tiles Specification](https://docs.mapbox.com/vector-tiles/specification/)

3. Update the Batfish configuration

You will need to update the Batfish configuration to define the wrapper component for the partial markdown files and load the split-pages Batfish helper function.

SplitPage wrapper

Use the SplitPage component (@mapbox/dr-ui/page-layout/split-page) as the wrapper for each markdown partial file. You will likely also need to create a local wrapper component to pass the page's constants file to the component since the Feedback component requires data from the constants file.

1. Create a local component: src/components/split-page-shell.js.
2. Import the SplitPage component: import SplitPage from '@mapbox/dr-ui/page-layout/split-page';
3. Import the site's local constant's file.
4. Pass all props and the constants to the SplitPage component.

Example

import React from 'react';
import PropTypes from 'prop-types';
import SplitPage from '../../../src/components/page-layout/split-page';
import constants from '../constants.json';
 
export default class SplitPageShell extends React.PureComponent {
render() {
const { children } = this.props;
return (
<SplitPage {...this.props} constants={constants}>
{children}
</SplitPage>
);
}
}
 
SplitPageShell.propTypes = {
children: PropTypes.node
};

Define SplitPage wrapper in the Batfish configuration

1. Update batfish.config.js to define the new wrapper and using a logic, only apply the wrapper to files in the sections/ directory:

jsxtremeMarkdownOptions: {
getWrapper: resource => {
if (//sections//.test(resource)) {
return path.join(
__dirname,
'./src/components/split-page-shell.js'
);
} else {
return path.join(__dirname, 'src/components/page-shell.js')
}
}

• If you do not want the Feedback component to appear after each section (or partial markdown file), you can reference @mapbox/dr-ui/page-layout/split-page instead of the local split-page-shell.js in batfish.config.js.
• You can turn off the Feedback component from any partial markdown file by setting hideFeedback: true in the frontmatter of the desired section.

Use the split-pages Batfish data selector

The split-pages Batfish data selector will combine metadata and headings for all partial markdown files and create a single source for the main page to reference.

1. Import the buildSplitPages function in batfish.config.js.
2. Create a new splitPages dataSelector that returns the buildSplitPages function.

const {
buildSplitPages
} = require('@mapbox/dr-ui/helpers/batfish/split-pages.js');
 
module.exports = () => {
return {
dataSelectors: {
splitPages: (data) => buildSplitPages(data)
}
};
};

4. Create redirects

You will need to create redirects in subdomain-docs to redirect the partial files to the main file. The redirects will prevent users, or more likely web crawlers, from accessing the page partials.

See Redirects for Studio Manual reference "sections" pages #75 for a similar example.

Limitations

There are several known limitations to using split pages:

• All headings must be unique across all pages that come together on the main page.
• The order in each partial markdown file must match the order in which you import and declare each markdown partial in the main file.
• You must create redirects for each for the markdown partial pages. See Create redirects section.
  • All pages in src/pages/ will resolve at a URL on docs.mapbox.com. We create redirects for each partial markdown file to make sure users, or more likely web crawlers, do not index or reference this page.
  • While it's possible to store the partial markdown files in a directory outside of src/pages/ this will require updating the content-based tests to properly test and lint these page partials including all the pages in src/pages/.
• The main page must be a JavaScript file (not markdown). This will enable the scrollspy sidebar to sync properly with the content headings.

Tag debugger

This section makes sure the tag: beta frontmatter item works. The beta tag should appear next to the heading in NavigationAccordion.