Best practices when creating articles in dotCMS

Learn about the best practices for creating an article in dotCMS.

Showing final step buttons for Article content type, including Language, Save Draft, Check Links and Publish.

Use of News Feeds

Units should have a dedicated article listing feed for showcasing news within their unit. Units can also create supplemental article feeds for more specific listings.

Editorial Style Guide

ANR Communications & Marketing follows the Associated Press Stylebook for most editorial content, including online articles. Additionally, we follow the MSU Editorial Style Guide.

Other Resources

MSU Extension:

General Web Writing Best Practices

Think about

  • What the article looks like on a phone.
  • How easy content is to scan.
  • What search terms and tags would make it easier to find your article.
  • What images and summary would show when sharing on social media.
  • What areas of should the article show up on (e.g., department home and AgBioResearch home, 4-H home and Horses home).


  • Short sentences.
  • Short paragraphs (chunk content, one topic per paragraph, limit words to around 70 in a paragraph, or no more than four lines of text).
  • Subheads (Headline 3 in the text editor), especially in long article to aid in skimming and search engine optimization.
  • Clear and concise language (common language is best for search engine optimization and people).
  • Active voice instead of passive voice (Margaret taught the class. vs. The class was taught by Margaret.).
  • Bulleted or numbered lists when appropriate.
  • Contextual hyperlinks to internal and external web pages (don’t spell out URLs or use “click here” text).
  • White space to help for easier scanning, way to visually separate information.
  • For added visual interest: Use relevant photos, pulled quotes, embedded videos.

In dotCMS use:

  • Banner image with all articles to help set this content type apart from a general web page (general landscape images work well: 4,000 x 1,300 pixels).
  • Tags that are relevant to the article content.
  • Relationships that are relevant to organizations, people and datasets.

Articles Overall

Write in the inverted pyramid style, putting the most important information in the first paragraph, sort of like a thesis sentence.

Think about

  • Primary audience(s) of an article based on the content.
  • Goal of the article.
  • What you want people to do after they read an article.
  • Should a call to action be added?
  • Is there other related content that should be added, embedded, crosslinked, related, etc.?

Think carefully about keywords, search engine optimization and social media optimization when writing articles, titles/headlines and summaries/kicker lines, subheads and tags. What terms are readers likely searching for? See what comes up on Google when you search for some of those terms.

Include keywords that are central to the story’s content. Consider what keywords are relevant to the story and what may be trending in search engines and on social media.

Details in dotCMS

Title field

Only capitalize the first word and proper nouns in a Title.

Titles should be:

  • Short and direct (not include jargon, cleverness or technical terms).
  • Able to stand on their own and understood out of context of a web landing page (often articles are the first entry point to the website).
  • Search engine friendly.

Write Title headlines with a broad audience in mind, as often article readers will get to an article based on search or social media not web landing page, so overall article context is important.

The Title field is for your article headline. In most cases, you should NOT include a person’s name in the headline. The headline should be a general overview of the article. Can use well-known acronyms like MSU and CANR in a Title, but spell out on first reference in the summary/kicker and/or article body text.

NOTE: The Title is pulled into search results and crawled for keywords.

Summary field

This should be written as a sentence and should summarize the Article content in a little more detail from the Title.

The Summary field text could be similar to your first sentence/paragraph, but it should NOT be the same.

The Summary acts as an article’s kicker or second headline. Can include peoples’ names in this field. If referred to MSU/CANR in the Title, can use this to refer to a specific department or additional relevant organizations like departments, etc.

NOTE: The Summary information is what is pulled into widgets and social media when sharing. It is also part of search results. Readers and search engines don’t like to “re-read” the same copy twice.

Image fields

Image: This will be the image that is pulled into the top right of your article. The description you add is the alt text for screen readers, and should be a general sentence with a short description of the image.

In some cases, you may also want to add a caption. The caption should be different and likely more specific from the alt text. You may also want to include a photo byline in the caption.

NOTE: This Image field is the image that will be pulled when shared on social media unless a 3:2 Horizontal Image is also used.

3:2 Horizontal Image: This should be used when the Image field is vertical and won’t look right when auto-cropped by the system into a horizontal image.

It often makes sense to add a 3:2 image custom cropped option when a vertical headshot is used in the main Image field. The auto-crop feature for a strong vertically oriented image can cut off heads in a person’s headshot.

NOTE: The 3:2 Horizontal Image is used in article listing widgets, of which there are a lot of them used across, and on social media.

Square Image: May want to add a square image if you think the autocrop will be bad.

NOTE: The Square Image is used in some Home Page layout templates that use four boxes.

Banner Image: Recommend adding a Banner image (like a landscape, general MSU image) for all articles. This heightens the visual appeal of articles and creates a more unique design element to help visitors tell the difference more clearly from an Article vs. a web page.

NOTE: This is the background image for the article. Often best to use a landscape image. The Title and Summary text will be overlaid on the banner image. Dimensions: 4000 x 1300 pixels.

Date Published field

Insert the date that the article is or was originally published.

Author field(s)

Original Author: Use only if the original article author has left the university.

Byline: Use the Person: Child (Author-Article) Relationship instead of entering a byline in the field. This links to the person record and adds the article to that person’s page based on the relationship.

Enter name and email address into this field if the author isn't part of MSU or doesn't have a person record.


Every article should have at least one relationship, either to the organization and/or dataset. Articles can have more than one relationship. If a person(s) with a profile exists in dotCMS, and they are mentioned in the article, the Person - Child (Featured-Person) relationship should be made. If a person(s) with a profile is the author of the article, the Person - Child (Author-Article) relationship should be made.


Every article should have at least one tag for their unit (can be the name of the unit spelled out or the acronym), and the unit can determine what the tag says. It is also a good idea to include tags for a unit that encompass their overarching key topics/areas of expertise, etc. For example, academic departments could have tags for their degree majors, like Agribusiness Management. For example, for a unit like the National Charrette Institute, they could have a tag for charrettes.

After Publishing

Once an Article is Published, it also goes through a workflow process in the backend in dotCMS, and is assigned to different Extension and ANR Communications & Marketing communications managers to review and make any necessary editorial style edits.


Overall Article Examples

Is it a news story?

MSU earns $11 million USAID grant to help developing nations improve food security policymaking

Is it an internal story?

CANR names new assistant director of recruitment and retention

Is it a how-to?

Growing lavender in Michigan: Advice for a purple garden

Is it a Q&A profile?

Love of the outdoors and creativity make entomology a good fit for Max Helmberger

Is it a feature?

Michigan 4-H youth learn about importance of pollination & native bees

Is it a long-form article?

GMOs: A surrogate for the debate about agriculture?

Is it an event promotion article?

Smart ag: Where is it going? (2019 MSU Agriculture Innovation Day)

Is an event follow-up article?

MSU host annual Agriculture Innovation Day (2019 MSU Agriculture Innovation Day)


Good Examples: Title & Summary

MSU earns $11 million USAID grant to help developing nations improve food security policymaking

Michigan State University has received an $11 million grant from the United States Agency for International Development to implement a new Feed the Future Innovation Lab for Food Security Policy Research, Capacity, and Influence.

CANR names new assistant director of recruitment and retention

Jeff Keson was named assistant director for recruitment and retention in the MSU College of Agriculture and Natural and Resources, effective August 5, 2019.

MSU to partner with Egyptian Center of Excellence for Agriculture funded by USAID

Michigan State University is a partner institution on a five-year, $30 million grant from the U.S. Agency for International Development to establish an Egyptian Center of Excellence for Agriculture.

Four MSU affiliates elected to Board of U.S. Society for Ecological Economics

MSU faculty and students are hoping to make big contributions to the field of ecological economics.

How a simple chlorophyll meter can help to reduce your nitrogen application costs

Because nitrogen is closely related to chlorophyll levels, using a chlorophyll meter can help corn growers finetune their sidedress nitrogen applications.

MSU Food Science and Human Nutrition postdoctoral researcher awarded USDA NIFA Fellowship

Alyssa Beavers has received funding from the U.S. Department of Agriculture for a project investigating impact of gardening on the human gut microbiome and antibiotic resistance.

Michigan 4-H youth learn about importance of pollination & native bees

Local Michigan teens were given the opportunity to teach and guide the youth through the Native Bee Challenge, to educate them about the habitat of native bees and how they benefit the food supply and agriculture.

MSU and EPA researchers examine nutrients and aquatic plants in variety of water bodies

A team of scientists from Michigan State University and the Environmental Protection Agency examined patterns of nutrients and aquatic plants in lakes, wetlands and streams. A paper on the project was published in the journal Ecological Applications.

How to protect pollinators in urban landscapes and gardens

A new 2019 update is now available for the most complete guide to protecting pollinators while gardening, growing flowers or managing trees, shrubs or turfgrass in urban areas.

Did you find this article useful?

You Might Also Be Interested In