Sharepoint folder structure

Generally, all folders for the website are flat, meaning there are no nested folders within them. This is a difference from the previous folder structure which divided items by category. For example, articles tagged with “design system” were all inside the “design system” folder, which was in the “stories” folder. Now, all articles are inside the “ideas” folder regardless of tag.

404

This folder contains the content for random 404 images. These documents include the image, and a caption to display with the image.

It is not user-facing, which means users shouldn’t find published pages within the folder unless they know the exact URL to get to that page. Pages that are not user-facing won’t show up in search.

Authors

This folder contains the content for authors. These documents include the author’s name, an optional job title, a photo, and a description.

It is not user-facing.

Careers

This folder contains career listings. See Migrating career listings for more.

Drafts

This folder has historically been used to stage articles before publishing on the live site and can also be used for developers for various test pages.

It is not user-facing.

Ideas

This folder contains articles. See Migrating articles for more.

Besides articles, this is where the pages for tags pages and curated editorial pack pages are created.

Partials

This folder contains the content that is repeated across the website. For example, the document that determines the links appearing in the navigation menu are here, as well as the prefooter block that appears at the bottom of every career listing.

It is not user-facing.

Pattern Library

This folder contains documentation for the blocks, layouts, and auto-blocking used on this website. This is also where content editors will find the document for this migration guide, as well as a page listing all published pages on the site.

Migrating articles

Metadata

Ensure the article has Title metadata, which should reproduce the headline of the article.

The Image metadata should reproduce the main image used in the Article Header (see Auto-Blocking below), and the Image Alt metadata should contain the alt text of that image.

The Tag metadata can now support multiple tags. Remember to separate multiple tags by a comma.

The Color metadata should be replaced with the Theme metadata, which only accepts values from the approved list of Gradient Themes.

The Author data can support multiple authors. Remember to separate multiple author names by a comma.

Auto-Blocking

Instead of adding the headline, subtitle, image, and image caption in the document in a specific order, we will instead be using the Article Header block to create the header.

Updating Blocks

Instead of adding the headline, subtitle, image, and image caption in the document in a specific order, we will instead be using the Article Header block to create the header.

The H2 with Attribution block should be updated to use the Quote block. Note that this will remove a heading from the page.

Any Pull Quote blocks should be updated to the Quote block.

Images can be added to the document as before, but the Image with Caption block allows for additional styling to be added to the image, such as making the image full-bleed or showing two images side by side in a 50/50 layout. The Image with Caption block also allows for explicit setting of `alt` text, a requirement for an accessible experience (unless the image is merely decorative.

Any Multi-Image block should be updated to use the Image with Caption block, and placed within the correct layout to display the images in the correct two-up or three-up layout.

The Image with Text block should not be used. Instead, create a 70-30 layout using the Plaintext block and an Image with Caption block, as described on the Layouts page.

The Additional Reading block should be deleted; its content can be rendered via plain Sharepoint text.

Any CTA blocks at the end of an article document should be deleted, as this block no longer exists. A call-to-action is now automatically inserted as part of the article prefooter, the content of which can be found in the Partials folder.

The Lede block can be used as before.

Migrating career listings

Metadata

Ensure the Location metadata separates the locations with a comma.

Ensure the Job Listing metadata is filled in with the link to the actual job application.

There are two new metadata fields: Discipline and Team Name.

The Color metadata should be replaced with the Theme metadata, which only accepts values from the approved list of Gradient Themes.

Migrating author pages

Metadata

All author content can be migrated over without issue, but content editors should add a Metadata table with a Robots field containing “noindex” as the value. This will prevent web crawlers from indexing the page.

Using the `query-index` file and how it is set up

AEM keeps an index of all published pages in a query-index spreadsheet, which we access for many of the dynamic sections of the website such as the Ideas page filtering, recent ideas block, search, etc.

Note about custom index definition in the repo

The code also contains a “helix-query.yaml” custom index definition which determines which data is indexed. We use this configuration file like the previous site did, rather than the automatic indexing, as the automatic indexing does not properly bring over some metadata (especially metadata fields that are more than one word).

Query-index file and sub-sheets

The root of the Sharepoint folder contains the “query-index.xslx” file. Within this is the first sheet called “raw_index”, which is what the running AEM integration will automatically update when a page is published or unpublished. This list of content is the source of truth for the other sheets.

The additional sheets within this file “shared-default,” “shared-ideas,” “shared-authors,” etc. are locked and should not be modified. These sheets contain spreadsheet formulas in the first cell that are filtering and copying all the needed rows and columns from the raw_index, and in some cases are excluding pages that have “noindex” in their “robots” metadata.

Managing content and editing the query-index

There are a couple of important ways that this affects managing the content. Most of the time this file should not need to be manually edited. For new content to be added, or existing rows of content to be updated, “Publish” must be used. For content to be removed, AEM has an “Unpublish” that should be used.

If an article happens to be deleted or moved but not unpublished, it may still exist in the “raw_index” and the AEM integration won’t know to delete it. In that case, the “raw_index” can be manually edited to delete a row. Otherwise manually editing the content of an existing row in this spreadsheet is not recommended as it would be overwritten when the next update to that piece of content is published.