Welcome to the Global Voices Posting Guide. This is designed to help you with the more technical side of creating GV content.
If you are not a Global Voices contributor yet, please see the Get Involved page to learn how to become an author or translator.
- 1 GV WordPress System
- 2 Post Settings
- 3 Text Formatting
- 4 Adding Images
- 5 Adding Videos
- 6 Adding Sound
- 7 Adding Social Media
- 8 Embeds to Avoid
GV WordPress System
To write for Global Voices, you have to log in to the GV WordPress installation. WordPress is software we run on our server that makes it easy to write posts.
Authors should receive a login name from the editor who creates their user account. The system login page for WordPress is always available by adding /wp-admin/ after the URL. For Global Voices in English, it's: globalvoices.org/wp-admin/
If you don't have a password or have forgotten it, simply use the Lost your password? link and the site will email you a link to reset it. Remember to make your passwords unique and complex (capital letters and symbols) for security!
If you want to learn more about WordPress, there's good documentation on their wiki.
Generally speaking, the main task you'll be using WordPress for is creating posts. To get started with a new post, click Posts in the sidebar, and choose New Post.
Posts in WordPress start off as a Draft, which means the post is only visible to you and editors. Eventually your post will get the Published status and be visible on the site itself. Only editors on the site have the ability to publish posts, so you need to use the Submit for Review button on the post and notify your editor that it's ready to be edited and approved.
The content of your post inside WordPress will be autosaved on a regular basis, so you should never lose your work, but it's still good to press the Save Draft button sometimes to ensure that your changes are properly recorded. While you are logged in, changes to posts will automatically be associated with you, and you can go back to old versions of posts using the Revisions block in the post editor.
For a detailed screencast, watch How to write a post for Global Voices created by Izumi Mihashi, Japanese Translation Manager.
Notifying Your Editor
When you are happy with your post and have gone through the Story Checklist to make sure it's ready, you should send it to your editor for review. The most basic way to do this would be to copy the URL of the story (in the address bar of your browser) and email it to your editor.
A better way is to make use of the Edit Flow tools in the post editor, specifically the Notifications and Editorial Comments boxes at the bottom.
Subscribe your editor in the “Notifications” box, then add an “Editorial Comment” so they get an email.
To notify your editor is to scroll to the bottom of the post editing screen to find the Notifications block, search for your editor and tick the box next to their name.
That will “subscribe” them to the post, so they will receive an email notification when the post's status changes or when someone adds an Editorial Comment. Keep an eye on their name and make sure the background flashes green, indicating that it saved correctly. If you aren't sure re-save the post and make sure their name is still checked in the “Selected” section of the Notifications list.
Once your editor is subscribed in the Notifications block, go to the Editorial Comments block and leave a new comment explaining that the post is ready, or asking any questions you have. The comment and a link to your post will automatically be emailed to your editor
Pushing the Submit for Review button, which will give your post Pending status, will also send an email to your editor, but it's important to remember that the “Submit for Review” button only sends an email the first time you press it, so just in case you should always leave an Editorial Comment at the bottom when your post is ready to be edited.
For more details about how the notification system works see the Edit Flow page.
Visual and HTML Editing Mode
The post editor in WordPress includes a Visual (what you see is what you get) mode as well as the raw Text (HTML) mode. Posts for Global Voices should work in both modes, so you can use whichever best suits your style and needs. The Visual mode is usually more comfortable for writing, while the HTML mode is extremely useful when you need to figure out a tricky problem.
Aside from the editors built into WordPress, it is a good idea to also use a text editor on your local computer as a backup. Regularly copying your post into a text file and saving it is insurance against a mishap with the website that could potentially lose all your hard work.
Looking for a good, free text editor that works well with HTML? Get the Atom Editor. It's built by Github and works great on all systems and supports all kinds of coding languages including HTML.
Important: Never copy directly from Microsoft Word!
Pasting text from Microsoft Word into WordPress will cause many formatting problems that can be a disaster to fix. If possible, avoid Microsoft Word entirely. If you must use it always paste the text into a simple plain text editor, then copy it again before pasting into WordPress. This will remove the bad formatting of Microsoft Word. Alternately, you can use the “Paste From Word” button in the Visual editor, which should insert the content while removing the unnecessary formatting.
Important: All code in GV posts should work in both Visual and HTML editors!
Occasionally you may want to use HTML in your post that is deleted or broken when you switch to the Visual editor because of automatic “validation” it performs. Often this happens when embedding an object from a third-party site, like a video or slideshow. When this happens it's tempting to just avoid the Visual editor but you must not do so. Many authors, editors and translators within GV depend on the Visual editor, and any one of them might open your post in the Visual editor, thus breaking your code and making the post confusing to readers. Always make sure that the final code in a post works in the Visual and HTML/Text tabs of the editor before publishing.
These are the core aspects of a post that need to be set up for every story.
All posts should have a short excerpt that is a compelling tease of your story. The text is edited in the Excerpt box of the post editor, which has a word counter to remind you of the maximum number of words you should use (it turns red when the excerpt is too long).
Excerpts appear on the homepage and other post listings on the site, as well as on Facebook and other social sites when a post is shared.
If a post doesn't have an excerpt, one will automatically be created from the first words of a post, but the results are rarely interesting and often cut off mid-sentence. For advice on how to write a compelling excerpt, please read Tips for Writing Tempting Excerpts.
Featured images are the “thumbnails” of GV, an image you choose to act as the promotional image for a post. We generate your chosen image into several large formats and use them in different places like the “Featured Posts” slider, or thumbnails next to post excerpts.
Featured images aren't automatically shown on the post itself, so they should also be in the body of the text with a caption for proper attribution. See the Adding Images section below for general information on uploading and embedding images.
Choosing a featured image
- Find the Featured Image box in the right sidebar of the WordPress post editor.
- Click Set Featured Image to open the image uploader popup.
- Either use the Upload Files to upload a new image or go to the Media Library tab to see a list of photos already uploaded.
- Click the image you want and use the Set Featured Image button in the bottom right corner to save your choice.
Once you've chosen an image the Featured Image box will display it along with previews of how it will look in different parts of the site.
Note on small images: If the image you chose isn't big enough the Featured Image box will have a red X WARNING! stating the desired minimum size and the size of your image. You don't have to find an image that is bigger than the minimum, but if your image is a lot smaller than know that it will look very pixelated when used on the site.
Cropping featured images to fit better
For best results featured images should only contain what's important in the image and have the main subject centred vertically and horizontally so it looks good in all aspect ratios (which might be square, or very “widescreen”). Often cropping the image before uploading is the best way to make it as powerful as possible.
You can crop the image on your local computer (on Mac the built-in “Preview” app works well) or use the image cropping tool inside WordPress after uploading.
Note that if you are cropping an image just for use as the Featured Image you should first re-upload a fresh copy of it, then crop and use that as the featured image. This is because your crop will affect all uses of the image including those embedded in the post, so you should only crop the original image if you want your crop to apply to the post as well as the featured image.
Global Voices posts are sorted into many different categories so that visitors can find posts about specific places and topics. It takes time because there are so many, but it’s important to ensure all the categories relevant to a post are selected before publishing.
Authors and editors should never add new categories to the list, we carefully select each one to avoid making the list any longer, and they have to be added to all Lingua sites simultaneously, so contact the Technical Lead if you need help.
In the WordPress post editor the category box is in the right sidebar. Categories are sorted by their types (WORLD, TOPIC) then alphabetically within each type.
Region and country categories
GV has a full set of country categories organized into detailed regions. To find a country first find “WORLD”, then the appropriate region, then the countries will be inside it. Here are some quick guidelines for choosing the right countries and regions for a post:
- When you tick a country category always tick its parent region as well.
- You can choose multiple regions and countries as long as they are all the subject of your post.
- That said, only choose countries that are really related. Ask yourself “would this story make sense in a list of posts about that country?”
- If your post is about a region generally but not a specific country you don't have to choose a country.
- If your post is about the entire world but no country or region in particular then don't add any categories, it will automatically show on the homepage. Never tick all the regions!
Select as many topic categories as are specifically relevant to your post.
If you aren't sure exactly what a topic category means visit it's archive on the site and see what previous posts were about. When in doubt only use the categories you're sure are related to a post.
GV uses language categories to indicate that a post contains quotes and references to citizen media in that language.
If a post was written in English but has translated Chinese blockquotes and links to a Spanish news story, the Chinese and Spanish language categories should be selected.
Note that language categories are totally separate from country categories and the “main” language of a country. If a post about Tunisia has French quotes then use the “French” category, not “Arabic”.
Remember: The language the post is written in should not be checked as a category, only the languages of the external content being linked to.
GV uses type categories to help users find posts with a particular type of content.
- Quick Read posts are short posts that link away from GV. See Quick Reads.
- Photo posts contain several compelling photos, and have those photos or photography as a central topic. (i.e. not just an example photo to illustrate the topic, but photos that are the topic).
- Video posts contain video of some kind.
- Podcast posts are about a podcast online and preferably have links to listen to audio.
- Featured posts are chosen by the managing editors to be promoted to users. Authors should not use this category.
Starting in 2015, the Global Voices sites use a plugin to add a “geolocation” to each post. The geolocations are used to display embedded Google Maps with pins for each post.
To save a geolocation in the post editor:
- Scroll down to the Location box.
- Use Find a new location field to search for a specific place.
- Make sure the pin is in the right area on the map.
- Save your post.
The location is saved as co-ordinates that define where a pin should show, but you can search for almost anything and Google Maps will predict what co-ordinates will work.
- Be as specific and precise as possible, if there is a city or neighborhood please use it rather than the country.
- Avoid using the same spot over and over, the map works best when pins aren't directly on top of each other.
- If there are multiple countries/locations in the post pick the most appropriate one to geolocate it.
- Consider a user clicking the pin and try to find a place that makes sense for the story.
- If there is no clear location for a post don't geolocate it at all.
Not every post needs to be geolocated, we can leave this box empty for stories about the whole world or with many equal locations.
The “permalink” of a story is the text used in its URL to identify it on the site. Anyone who uses links to your posts will see the permalink before they click, and search engines like Google use the words in permalinks to know what they are about, so it's very useful to have the words people will search for related to your story inside the URL/permalink.
Default Permalink: In WordPress the permalink of a post is, by default, automatically generated by converting the title into a URL (replacing spaces with dashes and removing any special symbols and punctuation). This system is very useful because by default it makes sure that keywords in your title are in your URL, but it isn't always the most effective. Some kinds of headlines, like questions or “teasers” designed for sharing on social media might not have all the important keywords in it, so it's often good to edit the permalink and make sure that it is the ideal URL, regardless of what you chose as your title.
WARNING: Never edit a permalink on a published post!
As soon as a post is published it's URL is sent out to the internet in our RSS feed and many other ways, and changing the permalink will make all those links lead to 404 errors, so never edit it after this point unless there's a very important reason! Instead always double-check the permalink before publishing your posts.
Editing The Permalink
A draft's permalink can be edited using the Permalink display right below the post's title on the edit screen. Once a draft is saved you'll see the Permalink listed along with an Edit button. Clicking Edit will show a field where you can change the text, then click OK when you're done and save the draft immediately to make sure your changes aren't lost.
Note that you should never leave empty spaces or special symbols in URLs, instead keep it to simple words separated by hyphens (-).
By default WordPress only supports a single creator for each post, but on Global Voices the Lingua translation system has the option of setting Additional contributors on posts, all of whom will show in the credits and have the post listed on their profile page.
Deciding which contributors qualify as “co-authors” of a post is up to you, but setting them is easy: Find the Authors box in the sidebar of the post editor and click the +Add New button to add a second pulldown menu with the list of authors. Choose the second author, repeat as necessary then save your post. To remove an additional contributor click the red x next to their name.
Note: All “contributors” on a post will show as the same “type” of credit, either “written by” or “translated by”, based on the post where they were set in the author box. If the post was an “original” then they will show as “written by”, if it was a translation, they will show as “translated by”. So if you want someone to show as “written by” you have to add them on the original post, even if they did their writing on the translation post. This will probably never come up for you, but keep it in mind in case you ever find your extra contributors aren't being credited properly on posts.
Tagline is a simple line of text that will show below the post's title and above the rest of the content. Read about taglines in our post introducing them.
Each post should have a tagline for consistency. Taglines can share text with the excerpt since they never show together, but shouldn't repeat the first line of the story.
The HTML contents of this box will be displayed next to the post content at the top of the sidebar, above the author/translator credits and any other widgets.
Use this tool to add any content that is very important to have visible immediately, but which doesn't make sense at the start of the post.
The box uses raw HTML tags, so if you aren't comfortable writing HTML by hand, create the content for this box in the Visual Editor, then copy it from the Text editor and paste into the setting box.
Ticking this box will hide the sidebar of the post entirely, making your text much wider in the process. Use this tool when something in your post is improved by being extra wide.
Remember: All posts on Global Voices are “responsive” and will often be shown at mobile screen sizes. If the content of your post is so “wide” that it doesn't allow room for the sidebar, consider how it will look when viewed on a phone.
Below are the various text formats we use in our posts. In all cases, they can be added with both the Visual Editor (WYSIWYG) and the Text Editor (HTML). If you require formatting that isn't listed below, contact the Technical Lead for assistance.
HTML blockquotes should be used for any text taken directly from an external source that is more than a few words long.
<blockquote>Quoted text goes here.</blockquote>
Remember that quotation marks are not necessary in a blockquote unless the quote itself contains them.
In the WordPress “HTML” editor, you can either type the <blockquote> tag directly or select the quote text and press the b-quote button.
If you have text selected, the “b-quote” button will add the <blockquote> tags around the text; otherwise it will open a new tag or close the current one.
In the “Visual” editor you can use the quote button (giant “ marks) to create blockquotes.
If you have text selected the button will convert it into a blockquote, otherwise the button will turn the current line into a blockquote (or turn it into non-blockquote normal text if it's already a blockquote).
Tip: If you are editing a blockquote in the Visual editor and want to “get out” of it, hit Enter to create a new line inside the blockquote, then use the quote button to disable the blockquote for the current line, which ends the quote on the line above and lets you do something else with the current line.
Not all quotes require a blockquote tag. Some can be included in a post simply using quotation marks. Please see the Style Guide for more details.
When a post contains a long quote in a different language you should always include both the original text in a blockquote (see above) and the translated text in a Translation Quote. Translation quotes are powered by the .translation class, which changes the style of a quote so that when a normal blockquote and a Translation Quote are one after the other, the relationship is clear from how they are designed.
<blockquote>Original Text</blockquote> <blockquote class="translation">Translated Text</blockquote>
In the HTML editor you can use the .translation button to wrap the currently-selected text in a translation quote.
In the Visual editor you can use the .translation choice in the Formats pulldown menu on the second row of buttons. This will convert the currently selected paragraph or blockquote into a Translation Quote.
If you can't see the “Formats” menu’: You need to push the “Kitchen Sink” button on the right side of the top row to show the second row which has “Formats” in it.
Tip: The .translation buttons work just like the quote button, see the Quotes section above for more details.
Right-to-Left Language Quotes
Arabic, Farsi, Hebrew, Urdu and other languages are written from right-to-left, so they need a special .rtl class that fixes how they are displayed when we quote them.
<blockquote class="rtl">بدأت تتوالى</blockquote>
In the HTML editor of the system there is a .rtl button that will wrap the currently-selected text in a right-to-left blockquote.
In the Visual editor you can use the .rtl choice in the Formats pulldown menu on the second row of buttons. This will convert the currently selected paragraph or blockquote into a right-to-left blockquote.
If you can't see the “Formats” menu’: You need to push the “Kitchen Sink” button on the right side of the top row to show the second row which has “Formats” in it.
Left-to-Right Language Quotes
When writing in or translating to a right-to-left language the opposite class, .ltr, is needed so that quotes in English or other LTR languages display appropriately. The process is the same as described above for RTL, but use the .ltr class and buttons in the different editors.
Pull quotes are a special formatting often used by magazines to emphasize a small excerpt of the article by “pulling” it out of the flow of the story and displaying it as large, dramatic text floating between paragraphs.
Pull quotes are usually aligned right or left so the rest of the story can wrap around them similar to how small floated images work.
Pull quotes are created by adding the .pull-quote class to a
<blockquote> tag (as well as either .alignleft or .alignright to make it float):
<blockquote class='pull-quote alignright'>This is a right-floated blockquote</blockquote>
In the Visual editor you can use the .pull-quote choices in the Formats pulldown menu on the second row of buttons. There are three choices: full width, alignright and alignleft. Choosing one will convert the currently selected paragraph into the relevant type of pull-quote.
If you can't see the “Formats” menu’: You need to push the “Kitchen Sink” button on the right side of the top row to show the second row which has “Formats” in it.
.factbox is a custom style used on GV sites that converts a part of the post into a grey box to distinguish it from the rest of the text. Use .factbox when you want to highlight facts, trivia or anything else that doesn't fit in the normal prose of the story.
When a .factbox is aligned with .alignleft or .alignright it becomes a kind of sidebar inside the post, taking up half width and letting the rest of the text flow around it.
Unlike some other formats, .factbox can contain other HTML types within it, such as lists (
<ol>), images and captions.
Fact boxes are created by adding the .factbox class to a
<div> tag (as well as either .alignleft or .alignright to make it float):
<div class='factbox alignright'>This is a right-floated .factbox</div>
In the Visual editor you can use the .factbox choices in the Formats pulldown menu on the second row of buttons. There are three choices: full width, alignright and alignleft. Choosing one will convert the currently selected paragraph into the relevant type of .factbox.
Converting a complex set of HTML (e.g. a heading, a list and an image all together) can be tricky, because the button will often make each HTML tag into it's own .factbox. For best results carefully highlight the entire section, including the empty space around it, before using the .factbox choice in the Formats menu.
It is important to credit everyone who helped create a post, not just the main author. We do this by listing additional contributors at the end of the post as there can only be one author per post in the system. A contributor could be someone who helped translate the post, did a lot of sub-editing, or helped in any other way.
Place the contributors paragraph at the very end of every post, under even any ‘Extra Notes’ (see below) added. This allows it to match the author credit directly below.
<p class=”contributors”>This post was proofread in English by <a href=”https://globalvoices.org/author/solana-larsen/”>Solana Larsen</a>.</p>
If you are listing the name of someone who is part of Global Voices, please always link to their GV profile page (like this one) so that people can find their posts and bio information easily.
In the HTML editor of the system there is a .contributors button that will wrap the currently-selected text with a .contributors tag.
In the Visual editor you can use the .contributors choice in the Formats pulldown menu on the second row of buttons. This will convert the currently selected paragraph into a contributors paragraph.
Extra notes can be used at the end of posts to add necessary context or information for readers, as well as to give a special style to updates to the post added after publishing.
The display and functioning of the .notes class is exactly the same as the .contributors class outlined above. All instructions apply, just use the .notes buttons and/or CSS class in either the Visual or HTML editor.
All posts should have an image at the top. If images are the focus of a post or it contains many beautiful photos, please select the Photos category. If you want to include an image in a post that is graphic or violent, please be sure to review our obscene, offensive and graphic content guidelines.
Any images added to a post require a source credit and explanation of permission. For more information on copyright and permissions for use, please refer to Multimedia Copyright and Attribution.
The most important image for each post is the Featured Image which acts as the post's thumbnail and is used automatically when a post is shared to social media. Please ensure every post has a featured image set, as well as embedding it in the post as described below.
Uploading and Inserting Images
You should always re-upload images from other sites to our WordPress installation before inserting them into a post. While it's possible to insert them using the image URL from another site (commonly referred to as “hotlinking”), it a bad idea to do so for various security and longevity reasons.
Steps to upload and insert an image:
- Ensure you have permission to use the image.
- Find the largest version of the image available (ideally over 800px wide).
- Download the file to your own computer.
- Rename the file so that its name is descriptive. This is important because Google shows results based on image names having keywords. For example:
- Bad: IMG003893.jpg
- Good: bangladeshcomputerlab.jpg
- Upload the file to WordPress. Click the Add Media button above the post editor, then the “Upload Files” link in the popup.
- Fill in the image metadata fields (described below) with as much detail as possible.
- Choose the alignment, link and size settings that fit your image.
- Use the Insert into Post button to add it to the post.
- The image will go where the cursor was before you pushed the Add Media button.
Image Shapes, Sizes and Alignment
Uploaded images can be inserted at three sizes: Medium (about half the post width), Large (full post width) and Full Size (Full is whatever size the image was before uploading).
If possible, posts should begin with a full-width “Large” image that illustrates the story and sets the tone. You can have as many other images as you want throughout the post, either photos at full width or right/left-aligned images at half-size.
Here are guidelines for choosing how to embed an image:
- Landscape Images (wider than tall):
- If a wide image is important, use “Large” size with no alignment (full post width).
- If the image isn't quite big enough for “Large” size, use “Full” (original) size with no alignment.
- If the image is small or poor quality, use “Medium” size and align right or left.
- Portrait Images (taller than wide):
- Tall images should usually be inserted at “Medium” size because the “Large” size will be too tall for smaller screens.
- Consider cropping tall images to square or 4:3 format so they can be shown at full width.
- Align tall images right or left.
- Right or Left-Aligned Images:
- For all aligned or floated images, use “Medium” size.
- Aligned or floated images will be shown at 50% of post width regardless of size.
- Avoid having many aligned images in a row. There should be paragraphs between them to avoid rendering issues.
Note on “Center” alignment: Images should almost never be centered in a post because it makes them fit badly against the frame of the site. Either use the “Right” or “Left” alignment (to make the image half width) or leave the alignment at “None” (which will make it left-aligned in most languages but right-aligned for right-to-left languages like Arabic).
Note on large images with intricate detail or text: If you have an image with small detail that readers need to see then there is no embed size that will show it correctly. Instead, you should add a note in the caption saying “Click to enlarge” then set the Link to setting (see below) to be Media File. This way users can click on the image to be taken to the full size, where they can zoom in on the details. Normally we avoid setting Link to to Media File because it's just the same image slightly larger (or the same size) but if the reader needs to see more detail, linking to the Media File is a simple solution that works on both desktop and mobile.
Note on super-tall infographic images: If a tall image must be more than 600px tall (i.e. an infographic where users are expected to scroll to see it all) then embed the “Full” (original) size rather than “Large”, but before uploading such an image please resize it to 800px wide to avoid wasting bandwidth.
For each image you upload, please look through all of the fields and settings before inserting it into a post:
Title: Short text identifying the photo, like a headline just for this image. If the image is a link people will see the title when they hover over the image.
Caption: Text that shows below the image. It should summarize the content briefly and attribute the author and source of the photo as well as indicate permission for use. Use HTML links (
<a href=''>) in the Caption field to link to the source of images. See the Images section of the How to Write for GV Guide for more information.
Alt Text: MANDATORY! Describe what the photo shows explicitly. Alt tag is used for visually impaired people to know what is in the image, so please always fill this out and make sure it complements the caption rather than repeating it.
Description (optional): A more detailed explanation of the photo, not used for anything by Global Voices, but can be used to help add context about the photo for future authors and editors.
Alignment: Whether the image will float to the Left, Center, Right or not at all. Avoid Center alignment entirely and use Left or Right for small or unimportant images as they will be shown at half-width. See Image Shapes, Sizes and Alignment section above for full guidelines.
Link to: Where the visitor is taken when they click the photo. Whenever possible choose Custom URL and enter the URL where you found the photo. Never use Attachment Page. The Media File option, which links to the original uploaded image, should only be used when the image has lots of small detail or text, and readers will need to zoom in to see it. Read the Note on large images with intricate detail or text section above for details.
Size: Whether to insert the Large, Medium or Full Size version of the image. For full-width images always use Large. For Rightor Left aligned images use Medium. See Image Shapes, Sizes and Alignment section above for full guidelines.
Tip: Always check how images look using the Preview button
Image embeds can have strange interactions with text styles that aren't obvious when editing a post. Before publishing always check the post preview to make sure everything looks right.
Animated gifs have a few special considerations compared to JPG and PNG files. If a gif is not animated then there is nothing special to worry about, you can follow the instructions above.
If a gif IS animated:
- For the animation to show you must use the Full Size version in the Size pulldown menu. The resized versions lose all animation.
- Some animated gifs are enormous (over 10MB) which means they will slow down the pageload and use up a lot of bandwidth for visitors.
- Please check the size of animated gifs and if they are over ~5MB consider embedding a resized (non-animated) version instead, then linking to the full animated version in the caption and on the image itself (set Link to to Media File).
Videos can be a dynamic addition to a post, either as the subject of the story or for background information or flavor. We don't usually create original video at Global Voices and our site is not set up to actually host custom video. We do, however, encourage you to embed video from YouTube or similar sites when it is relevant to your story.
Always describe the video and link to its original source in addition to embedding it. Please see the Style Guide for more details. If you want to include a video in a post that is graphic or violent, please be sure to review the graphic content guidelines first.
Make sure embeds work in both the Visual and Text/HTML tabs of the editor. Some embeds may not work in the Visual editor because of its strict standards even though they work in the HTML editor. You should never depend on using only the HTML editor in these cases, and instead find another way to link to the content. See the Visual and HTML Editing Modes section for details.
Embedding YouTube Videos
Embedding a YouTube video is easy, but it's important you do it the right way. The HTML code you can copy on the YouTube site is very finicky and can break when viewed in the Visual editor and/or when it is imported for translation. To avoid this issue, you should always use the simplified WordPress embed system. See the WordPress Codex article about embeds for more.
The process is simple: Copy the URL of the video you want to embed and paste it into the post on its own line, like this:
Here is a video that illustrates my point:
There you have it.
This system is great because if the video or the embedding system ever break your visitors will still see the link to the video. It will still work if you skip the
[embed] and [/embed]
tags, but if the embed ever stops working those tags will help visitors understand what you expected them to see.
Embedding Other Kinds of Video
The YouTube embedding system is actually very general (based on a standard called oEmbed), and a lot of other kinds of videos can be embedded the same way.
The full list is very long and includes Vimeo, Flickr, DailyMotion and Viddler, among others.
If you try the[embed]
method and it doesn't work, then you can use whatever HTML the video site gives you for embedding, but please make sure that the embed code works well with both the HTML and Visual editors.
If the Embed Just Won't Work
If an embed does not work with both the HTML and Visual editors (or if it doesn't work with either) you can always take a screenshot of the video and embed it in the post instead. Hyperlink the screenshot to the video from its original source so that when people click they will be taken to the video.
That is a foolproof method when things get too complicated and is not likely to cause any problems during saving or translation.
Amara, formerly known as “Universal Subtitles”, is a service that lets you add subtitles to videos hosted on YouTube. GV sites have some support for embedding videos with Amara subtitles, so translators are free to use the service.
To embed the video (after transcribing and translating it on the Amara site), use the normal [embed] system, but with the unisubs attribute set to 1. For example (this Russian video has French subtitles available):
Always link to the Amara-hosted version of the video
The main concern with embedding Amara videos this way is that in some cases, such as the AMP version of posts) they are rendered as plain YouTube, missing the Amara frame. This is better than being completely broken but could lead to reader confusion if the story assumes the subtitles are visible. So the rule to remember to always indicate in the article text that you expect the Amara subtitles to be there, and include a link directly to the Amara version of the video.
In the example above, the link to include is this one, where the video is shown with subtitles directly on Amara.org. By including the direct link, you enable readers to view the video with subtitles even if the embed isn't working for any reason.
Example warning text:
Check out our Using Amara To Subtitle Videos guide to learn how to add subtitles to videos.
Like video the method for embedding a sound file in a post with a player depends on the source of the audio file. For more, please watch the screencast How to embed an audio file into a Global Voices post by Georgia Popplewell, GV Managing Director.
Embedding soundcloud files only requires the URL of the audio file and the
[embed] tag, similar to YouTube:
The post will show a big player for the audio file.
Embedding an MP3
Embedding an MP3 that's already on the web is easy. Our podcasting plugin “Powerpress” has a shortcode that will output a small player for your audio:
Note: This will only output the small player. You should always have text above or below the player explaining what the audio is, linking to the source website and with a direct “download” link for the file itself.
Note: Please don't upload audio files to the GV WordPress installation! Our server is not set up for audio hosting and it is very innefficient. Instead upload your audio to Archive.org as described below.
The recommended way to embed audio files on Global Voices is to first upload them to Archive.org, then insert that file in the post using the MP3 method described above.
Why we upload to Archive.org
Archive.org is a non-profit similar to GV but specializing in hosting Creative Commons media for free. Their site is specifically configured to host audio and video, so it's fast and reliable even though it costs nothing.
- Visit archive.org/create
- Create an account or log in.
- Use the Upload tool and choose your file.
- Fill out the metadata options to the best of your knowledge. Specifically
- Give your audio a Creative Commons Attribution-only license (CC-BY) in the Licensesection by choosing “Creative Commons” then checking the box for “Allow remixing” (this matches the license used on GV posts).
- In Subject Tags add ‘globalvoices’ and any other tags that make sense.
- When it finishes uploading you'll see the media page for your item.
- Find the Download Options listed in the right-hand sidebar.
- Copy the url for “VBR MP3″ by right-clicking it and choosing “Copy Link Address” (or equivalent in your browser).
Inserting the file in a post Once you have the link copied, embed it in your post with [powerpress url=] as described above.
Note about archive.org URLs: There is a quirk in the Archive.org system where the URL you copy from the link is not the same as the one you arrive at when you click it, because you are redirected to a special optimized URL at that point. Please always use the original URL copied from the link (like https://archive.org/download/…) rather than the optimized one (which looks like https://ia902600.us.archive.org/…..)
We embed audio players from Public Radio International as part of a partnership with them.
Currently the best format for the embed (iframe) code is as follows, which is the default embed code they give with style='width:100%;added.
<iframe frameborder="0" src="https://www.pri.org/node/80307/embedded" height="75" width="320" style='width:100%;'></iframe>
Of course you would replace the URL with the URL for a particular piece of audio.
Note: There may be issues loading the PRI embed over HTTPS, so please ensure there is always a link to another site where the player is working.
Adding Social Media
Quoting and embedding social media from around the world is a big part of many Global Voices stories. Below are guidelines for the technical aspects of including content from various services.
In all situations, be mindful of other people's expectations of privacy in their online postings. Don't quote or embed postings that are private and consider the safety of the original author before quoting from any service. For editorial guidelines, please see the Commentary section of the Style Guide.
Embedding tweets from Twitter.com
The official GV method of embedding Tweets in WordPress is using the Embed HTML from Twitter:
- Find the tweet on Twitter.com
- Hover over the tweet and click the “•••more” button.
- Choose “Embed” and copy the Embed HTML that pops up.
- In the WordPress editor, click on the “Text” tab and find the place where the tweet will go in the HTML.
- Paste in the HTML from Twitter.
This procedure results in a
<blockquote class="twitter-tweet"> with the full tweet text as well as links, credit and timestamp.
By copying the embed code directly, we get a full copy of the tweet right in our post. When the post is viewed by readers, it will look fancier, with images, buttons etc, but behind that is a full backup of the tweet that will always be there, even if the tweet is deleted or Twitter itself goes offline.
For editorial guidelines on using tweets in a post, please refer to the Style Guide.
Note: Do not embed the Tweet URL directly!
Another way of embedding tweets from twitter is to copy the URL and paste it directly into a post, which is admittedly very easy and convenient. The problem is that embedding this way means that the actual tweet is not in our post, and if the tweet is deleted, the post will just show the URL, which will lead to a
404 error if clicked!
For the purposes of GV, this is not a worthwhile tradeoff, so rather than embedding URL's directly, we always use the method described above to get the embed code with the
To test if a tweet embed is URL-based or blockquote-based: When you're editing a post, both types of embed look very similar. To tell the difference, check if you can click inside the tweet and select text. If you can only click on the whole tweet (and see a blue box surrounding it) that is a URL embed, and needs to be replaced with the full Embed HTML as described above. If you can select and edit the text inside, then it is a proper embed!
Manually creating a tweet quote
If you're unable to use the official Twitter Embed HTML, but you know the content of the tweet, then you can create a new
<blockquote> like you would for any other quote. In the case of a manually-created Twitter quote, you should ensure that it has the following elements inside:
- The @name of the Twitter user linking to their profile.
- The full text of the tweet, including any links.
- If there are other @mentions in the tweet, link them to the relevant Twitter user.
Never insert a screenshot of a tweet into a posts
A screenshot of a tweet can seem like a simple solution, but has several flaws that make it unacceptable, including that they are not readable by visually impaired people and are hard for translators to manage. Please never use screenshots when quoting from Twitter or any other site where a proper embed code is available.
When the tweet isn't in the same language as your post, simply include a translation blockquote (
<blockquote class='translation'>) after the tweet embed code (
See the #Translation_Quotes section of this document for details and tips for using them.
- Only translate the content of the tweet itself. The links, date and username will already be visible inside the original tweet embed.
- Never translate the tweet embed code. Add a new translation blockquote for the translated text.
- Do not translate hashtags.
- If you need to add an editors note into your translation (e.g. to explain an abbreviation), wrap it in square brackets ([…]).
It isn't recommended to rely on embedded Facebook posts because they are volatile and often cause problems, but if you need to embed something from facebook, please use the following format:
Do not copy and paste the HTML embed code from facebook.com! It is important to use the [embed] format as above to ensure compatibility with the different ways GV articles are displayed. Using the raw HTML causes the embed to break in many scenarios.
For editorial guidelines on using Facebook content in a post, please refer to the Style Guide.
Images and videos from the Instagram sharing service can be embedded using the [embed] code with the URL of a particular item (like many other embed types). For example:
By default the embed shows the image, its text caption, the like button and the comment button. It's possible to hide the caption by adding hidecaption=”1″ into your[embed] shortcode:
[embed hidecaption="1" ]https://instagram.com/p/trxJ5qQS07[/embed]
This will cause the text and like/comments buttons to be hidden, so only the image, username and instagram icon are displayed.
Getting the URL of an Instagram post can be tricky, but it's fast and easy once you know how:
- On the page for a single image, just copy the URL and insert it in a post as shown above.
- On a user's page you'll see a grid of images. When you click on one a modal popup will load and the URL of your address bar will change to be the URL for only that image. Copy it and insert it in your post as shown above.
- On your homepage (list of full images with text) you can get the URL for an image by clicking the timestamp/date. Copy the URL of the resulting screen.
As with all embeds you should always have an explanation of why this post is important that includes a direct link to it in case the embed one day breaks.
Embedding an Instagram “feed” rather than single post: It's possible to embed a “feed” from Instagram, which basically means showing the most recent post, whatever it is, rather than a single post. This is not recommended inside normal GV stories, but you can learn about the [gv_instagram_feed] shortcode on the WordPress Shortcodes documentation.
All WordPress websites (including Global Voices sites) have the ability to embed posts, similar to how Twitter and Facebook work. This happens automatically in the WordPress Visual Editor when you paste the URL of another WordPress post onto its own line and hit enter. What you get is an automatic block that shows the title, and icon and some buttons.
These embeds are very convenient, but should be used with caution. They can confuse translators and it is much faster/more performant to use a normal HTML link in the post, rather than having an embed just for text and an image.
Translating WordPress Post Embeds
If you are translating a post with an embed like this one please follow the same instructions as given for Tweet embeds as described above. To summarize: Add a
.translation blockquote right below the embed and translate the important text (title and excerpt of the post).
NOTE: We will be improving the design of these in the future, and may revisit the recommendation against using them.
Embeds to Avoid
The embeds below don't work properly with the GV WordPress setup in one way or another, so they should be avoided until further notice.
Examples of these embeds along with more information about the problems they have, should be available on the Social Media Embeds That Don't Work page.
Tiktok is a video sharing service. The Tiktok embed code superficially seems to work fine on GV sites, but the AMP versions of our pages don't show them correctly. There may be support in the future, but for now we should not use these embeds. (view the /amp/ version of this page to see why).
Telegram is best known as a chat app, but posts can be made public, and when they are, they can be shared and embedded in WordPress like a Tweet. See the Telegram Post Widget documentation for more information.
<script async src="https://telegram.org/js/telegram-widget.js?7" data-telegram-post="telegram/83" data-width="100%"></script>
You can place this code inside a GV post using the Text view of the post editor. It will look strange in the editor, but when you preview the post, it should look normal.
AVOID TELEGRAM EMBEDS BECAUSE: While they work in normal post views, they are completely broken in the AMP versions of our stories, and thus they will be invisible to mobile users who find our stories in Google. Maybe in the future AMP will add support for Telegram embeds, but as of February 2020, there are no hits in Google for anyone even trying to solve this problem.
For the time being please use a regular
<blockquote to quote from a Telegram embed.
Another note: Currently the Telegram embed's output is hard to apply styles to, so if you have a .translation blockquote immediately following the embed it will look normal with a space in between, unlike Twitter where they are stuck together.
Storify is a social media aggregation tool we sometimes use to quickly assemble stories from Twitter and Facebook. We only use it in breaking news situations where the increased speed is vital.
AVOID STORIFY EMBEDS BECAUSE: “Storified” posts can not be translated directly because Storify stores the tweets in a locked-up format on their server. In order to translate a Storify embed, the entire story has to be re-created using the WordPress editor and Twitter embeds, which takes a lot of work.
For the time being, please just use regular Twitter embeds in the WordPress editor rather than using Storify.