Maryland Humanities is a WordPress site that utilizes WordPress’s block editor. Where possible, the site and theme leverage WordPress’s native functionality to achieve its goals. Editors who are not familiar with WordPress should start with Learn WordPress.
This user guide explains specific functionality for this site, and is not intended to replace WordPress Documentation.
Design Library
A catalog of all the site’s building blocks, including colors, fonts, block editor components, and complex design patterns.
Guides & Documentation
Training and reference materials for how to edit the site.
Report an Issue
Use this form to report a problem with the site, make a feature request, or ask a question.
Heads Up!
Before you begin editing, always make sure you are on the Production Server, not the Development Server. Check your browser’s url bar:
Production Server: https://mdhumanities.org/wp-admin ← do your editing here.
Development Server: starts with http://209.189…. ← don’t edit on this site!
After launch, the Development Server is used to test code changes and updates. It is a testing environment, and its content and database may be overwritten at any time!
Basic Content Guidelines
The Devoted recommends the following content guidelines for Maryland Humanities:
- New Tab Links: avoid opening links in new windows/tabs, even offsite links. Allow users to control how they open links on your site. Unexpected new tabs or windows can be disorienting.
- References:
- W3C G200: Opening new windows and tabs from a link only when necessary
- Washington State University: Open in New Tab
- Meaningful Link Text: ensure link text is descriptive about the content behind the link. Avoid link text that says only, “click here” or “read more.”
- References:
- Accessible Link Text Guide from Level Access
- Documents and PDFs: leverage Google Drive to host documents and PDFs instead of your web server, where possible. Ensure the document’s sharing settings are set to “Anyone with the Link” before linking to a Google Drive document. This allows your existing Google Drive to handle the heavy lift of large files, leverages your existing document architecture, and helps you more easily control access and versions.
Important Accessibility Guidelines
Headings: please see this W3C guide to Headings. It’s important to not skip heading levels, as they serve as waypoints in the page for screen readers and indicate content hierarchy. If you need a smaller heading, use the typography settings to adjust the size.
Background / Foreground Colors: pay close attention to the contrast warning when using the block color picker. The editor will check your selections and provide a notification if your foreground / background combination lacks sufficient contrast, but it will not automatically prevent low-contrast combinations.
Alt Text for Images: ensure all images have alt text that describes the content of the image. This can be easily added through the Media Library. Some images imported from the old Maryland Humanities site already have excellent alt text and can serve as a model for ongoing content development.
Using the WordPress Block Editor
The Maryland Humanities theme utilizes the WordPress Block Editor. The Block Editor allows editors to build rich content pages within the bounds of the Maryland Humanities design system.
WordPress Block Editor Resources:
- Learn WordPress Lesson: Using the Block Editor
- Learn WordPress Lesson: Nesting and Using Blocks
- WordPress Documentation: Work with Blocks
Helpful Editor Tips from The Devoted:
- Use the Document Overview to move and nest content.
- Leave the Settings Drawer open.
- Use style presets and avoid entering manual values. Although the editor allows you to enter manual values for font sizes, colors, margin, spacing, etc, it is best to use the existing style presets developed by your designer. These presets help define the design language of the site, and establish an important visual hierarchy.
Using Images and Media
Optimizing images: avoid using very large images, as they can affect your site’s performance and loading time. Minify and scale down images before uploading, and ensure resolution is 72dpi.
Aspect Ratio: the block editor has a built-in ratio tool that ensures images in news feeds are cropped to the same aspect ratio, so there is no need to pre-crop images. See image editing for details and videos.
An media categories plugin is recommended for the Media Library to keep images and media organized.
Site, Content, and Taxonomy Structure
Pages
Pages are intended for any content that is not news/events. See this Learn WordPress lesson for more information about the differences between posts and pages.
Sort Order / Menu Order: In the admin area, the page list is sorted by page order, then alphabetically if no order is set (or if two pages share the same order value). Page order also controls the order of sidebar menus.
To change a page’s order value, select Quick Edit below the page in the page list, and change the Order value. Lower numbers = beginning of list.
Special Settings for Programs
Programs Landing Page: If the Programs Landing Page ever changes — should the need arise to delete this page and make a new top-level landing page for Programs — the site settings must be updated. This is necessary because the navigation behavior is different for pages that are descendants of programs. Designate a new Programs Landing Page by selecting the new page in Settings > MDH Settings.
Program Category: pages that are part of a program should select a program category in their Page Settings. Program categories are used to organize contact information and display taxonomy tags in content feeds.
Editing a page’s sidebar
Change Program Contact Info: Program pages display staff contact info in their sidebars. Contact info is set for an entire program, and leverages Program Categories. Once a program has been added to a category, contact information should appear automatically. Edit the contact information for a program in Pages > Program Categories.
Subscribe Call to Action: You can turn off the Subscribe to News CTA in Page Settings. Under “Sidebar” in Page Settings, toggle the “Show Subscribe to News?” setting. This will show/hide the CTA on this page only. The CTA is on by default, so it will automatically appear on every page unless toggled off specific pages (for example, the pages in this User Guide have their CTAs toggled off). To edit the CTA itself, use the Patterns editor. The CTA is a synced pattern, so any change you make to it will be reflected everywhere the CTA appears.
Sidebar Extra Content: Page Settings also supports a WYSIWYG field for adding simple rich text content to a page’s sidebar. Use this if you need to add limited special content to a page’s sidebar. It will appear on that page only.
Sidebar Navigation: sidebar navigation is automatically generated. See Editing Sidebar Navigation for details and settings.
Choosing a Page Template
Page Templates tell WordPress how to structure a page. The following templates are available in your theme:
- Basic Page: this is the default template. It has a simple page title and a main+sidebar content area. Includes the site’s header, footer, and special CTA rows above the footer (Donate CTA and Testimonials).
- Landing Page: for top-level pages in the main navigation. Landing pages are full-width (no sidebar) and have large page titles. Includes the site’s header and footer.
- Simple Landing Page: simplified version of a landing page intended for pages with content insufficient for featured images or excepts. Exactly the same as a landing page, but has a smaller page title.
- News Landing Page: specific template for News & Resources that contains a filter/search bar.
- Fancy Detail Page: special combo of the header/page title from a landing page, but the main+sidebar content area from a basic page. Typical use case: top level page for a program.
- No Title Page: template with header/footer only, no page title. If you use this template, you must add an H1 with title to the page. Typical use case: special design page such as OMOB Reader’s Guide.
- Blank: completely blank page with no header, footer, or content container. This template is not currently in use, but is available if necessary.
- Calendar View / Single Event: special templates used by the Event Calendar plugin. Don’t apply these to standard pages.
Posts: News
Posts are intended for timely news content, such as news articles and press releases. These live under News & Resources and are served to news feeds throughout the site. See this Learn WordPress lesson for more information about the differences between posts and pages.
Using Post Taxonomies
Categories tell the site what kind of post this is: News, Blog Post, Press Release, etc. Pick ONE category per post. Post Categories are used to generate sidebar navigation for the News section of the site. WordPress will automatically assign the category “Uncategorized” to any post not assigned to a category. To prevent this category from appearing in navigation, ensure all posts are assigned to a category.
Tags are topics that site readers can browse, or that site sections may leverage to display specific content. Posts can have multiple tags, but strive to keep them limited. A starter list of tags has been created for common news topics, such as History Day, OMOB, Grants, etc.
Tagging Suggestions:
- Although posts can have an unlimited number of tags, avoid over-tagging. Aim for 1-3 tags per post. Most posts should only need one tag to define its topic.
- Avoid creating tags for one-off topics. Only create tags for topics that appear frequently in your content.
- WordPress tags are not meta tags. Adding lots of tags will not impact SEO.
- Remember that tags can be used to serve topical content elsewhere on the site: “Recent Grant News” is possible only if the Grants tag is populated with news about grants.
- Also keep in mind that tags appear as a sidebar navigation item on news posts. This allows readers to browse information based on their area of interest. This navigation item loses impact if each tag has only one related article.
- The Devoted recommends that the web team chooses a defined list of top-level topics and restricts tag bloat.
Navigation
Not all navigation menus on the site are edited in the same way. This is intentional, to provide control where needed (main nav) and eliminate repetitive work where possible (sidebar nav).
Editing the Main & Footer Navigation
The site’s main navigation appears at the top of every page below the logo. New items must be manually added to this menu. Manual curation of the main nav prevents it from becoming crowded, overwhelming, or difficult to use. Manage the Main Nav in the Navigation editor.
Header Donate Button: if the donation link ever changes, it is important to update both the desktop and mobile versions of the donate button. The mobile version is hidden in the editor (since it is hidden until the menu is opened by a user), but its link can be changed by editing the MDH Header pattern and selecting it in the Document Overview. [Example video].
Footer Nav Menu: the navigation menu in the footer is also managed through the Navigation editor.
Editing Sidebar Navigation
Sidebar and tertiary navigation are automatically generated based on page hierarchy.
- For a page to appear in the sidebar navigation of a certain section, it must be a child of that section’s landing page.
- You can designate a parent page in a page’s settings: open Settings Drawer > Page Tab > Parent.
- Order of sidebar navigation items is determined by each page’s sort order.
Descendant Pages: for pages that are not programs (for example, grants or giving), sidebar navigation will include the top level/parent page and all of its descendants. If a page is part of a program, its sidebar navigation will display only pages from that program — not all descendants under /programs.
Show All Sidebar Nav Items: Descendant pages deeper than three levels are automatically hidden in the sidebar nav and shown instead in tertiary button links below the page’s title. This is intended to improve the mobile navigation experience. You can disable this feature on a per-page level by toggling the “Navigation: Show All?” setting in Page Settings. This will disable the tertiary/button navigation and show all items in the sidebar. This is demonstrated in the Editing Sidebars example video.
Plugins and Tools
The site’s theme, Maryland Humanities, is a custom theme created by The Devoted. It is adapted from Frost, an open source development theme by WP Engine. The Devoted uses GitHub to manage the project:
- GitHub repository for the site/theme
- GitHub project: issues, planned tasks, and development history.
The site and theme leverage WordPress’s native functionality as much as possible to limit reliance on third party tools and simplify training. For requirements that WordPress can’t meet, we rely on plugins. The following plugins are used to enhance the site’s functionality and recommended for use:
- Advanced Custom Fields Pro (ACF): ACF is critical to the structure of the site. Please do not disable or uninstall it.
- The Events Calendar Pro: used to manage event content.
- Admin Menu Editor: allows hiding/tidying up of the WordPress admin menu.
The following plugins allow the creation of blocks that the site’s templates and/or design patterns depend on:
- Breadcrumb Block: generates breadcrumb links for interior pages.
- Icon Block: adds an Icon option to the block library. Supports custom SVG icons, which can be added on request. Used by several design patterns.
- Carousel Slider Block: adds a simple carousel to the block library.
Post-launch Recommendations
The Devoted recommends the following tasks and considerations for the MDH team after launch:
- Add meta descriptions to posts and pages. The site has a built-in meta description field in Page Settings, or you can leverage the Yoast plugin.
- Ensure all images have alt tags.
- Set a schedule to periodically audit and prune old or outdated content.