Writing Content

Article Titles

When you're writing a title for a page or section, write a statement instead of a question. Those extra "who/what/why" words aren't necessary, and statements are easier for readers to scan quickly.


Include a short one or two-sentence summary about the document to help the reader confirm whether they’re in the right place, and improve search engine indexing.

Example: A Hero block is usually the first thing your visitors see, making it a great spot to get them acquainted with your catchy content. Controlled by a smooth parallax scrolling and featuring a fullscreen background image or video, this is the perfect place to make a great first impression.

Links and additional resources

It’s rare that a document lives on its own. Tell people where to go for help if they have questions and provide a link whenever you’re referring to something on an external website. Use links to point users to relevant content and trusted external resources.

For documentation and guides, you might say:

For more information, see the Adding your logo

For Upstairs blog posts and other trusted sources, you might say something like:

  • Example 1: To learn more about how to build your website footer, you can read this article which walks you through our entire process of redesigning out footer that you can easily put in practice.
  • Example 2: We’ve written an in-depth piece on building the website’s footer which comes in handy if you are looking to understand […]

If your work relates to several other documents, pick the most important ones or gather the links in a section at the bottom (e.g., Additional reading section)

If you need to link to other visual elements (images, gifs, videos), introduce those links in a similar fashion as shown below:

Trusted external sources

Linking instructions: 

  • When linking to another documentation article, remove the theme name from the URL (if the URL is pixelgrade.com/docs/rosa2/social-networks/… change it to pixelgrade.com/docs/social-networks/…).
  • All our blog posts have been moved to the /upstairs/ link, so links that contain /blog/category/ (e.g., pixelgrade.com/blog/culture/transparency-report-5) must be replaced with the new links (e.g., pixelgrade.com/upstairs/transparency-report-5)

Reference for this section