You are viewing a degraded version of this page. Please use a supported browser for the best reading experience.

Editing an Article

The Codex Press editor is designed to be a thin yet friendly wrapper for HTML, the language used to describe the structure of web pages. It may take a small bit of work to learn about HTML and how to write it with Codex, but we promise it’s not too painful. And best of all, you’ll be learning how the web itself works, knowledge you’ll be able to apply to all the future web projects you undertake.

Styling Content with Classes and Elements

At the heart of HTML are so-called tags, denoted with the symbols < and >. Tags wrap the text that becomes different parts of the page, giving them styles and—crucially—meaning as well. For instance, there are <p> tags which wrap the paragraphs on this page and tell the browser and bots such as the Google search engine crawler that they are meant to be interpreted as paragraphs of text.

<p>Pargarphs, as well as all parts of the page, appear within tags.</p>

The Codex editor mixes the convenience and style of a modern text editor with the full power of HTML. The key to this power lies in the line of grey text above every paragraph in the editor. Typing here will change the tag for the text below it. It will also let you add a “class” to the paragraph, which can also change it’s appearance and meaning.

Part of this document shown in the Codex Press editor. The first line has the a heading tag, <h1>, while the paragraph below is denoted with the <p> tag.

Codex uses a shorthand for specifying which HTML element you want to create. Instead of wrapping the paragraph or text in tags with < and>, you just type the element name above it. If you type a word that’s not a supported element or follow the element name with more words, they become classes. For example, typing “section two” would make a <section> tag with the class two.

The built-in themes contain a wealth of classes that let you add or control styles for common features of articles. If your publication is using its own theme, enquire with the developers on your team which class names are available for use. You are also free to invent new class names as you see fit and reference them later in CSS to change the appearance of text.

Class names on Codex follow a stricter pattern than in HTML and CSS. They will only be lowercase and will swap underscores (_) for hyphens (-), following convention.

Making an <aside> element with the pullquote class in the Codex editor.

One quirk of HTML is that it collapses blocks of multiple spaces and empty lines into a single space character. This helps preserve the readability of the source code and prevents your documents from containing empty space for cosmetic reasons. In this spirit, Codex will not insert empty paragraphs into the page. It’s also why the editor does not permit you to add two spaces, even after a period—the readers browser would just remove the space anyway.

To add blank space, you can add it in CSS using properties such as padding and margin. While this might seem annoying at first, it’s actually a quite useful “separation of concerns,” as geeks might say. Blank space is a design question that is best handled with other design questions in CSS. If you were able to create empty space in both places, things could get quite confusing.

You can style text within one paragraph by selecting it and using the menu that pops up. Select text, focus the input field in the resulting menu and type the name of the tag or select it from the dropdown. Please refer to the HTML reference for help on which tags are appropriate for your various purposes.

To add a link, we use the <a> or anchor tag. Type “a” in the field and then type or paste the link in the href field below it. Please note that this process is a little more finicky than, say, the browser’s location bar. For example, if you put “www.twitter.com” into the href input, Codex will create a link in HTML like <a href="www.twitter.com"></a> and the browser will think you’ve added a link to https://codex.press/www.twitter.com, or in other words, an article on Codex slugged “www.twitter.com.” To solve this problem, you must add https:// or http:// to the start of outside links.

Links to other stories on Codex should start with / followed by their full internal path. For example, a link to this page would have the URL /docs/text added to the link input.

Using Semantically Correct HTML Elements

As an author on Codex, it’s your responsibility to know how to use HTML elements correctly — but don’t worry, save for a few gotchas explained here, it’s quite straightforward.

The HTML standard defines the meaning behind different elements used in markup. This is important for a well structured document because it aides developers writing code to style the page and bots like search engines which need to understand it (as bots, they really need your help). It is also vitally important for accessibility because screen readers will rely on the elements you chose to understand how to communicate your content.

You’ll notice that in Codex there’s no button for “underline” or “bold.” This is intentional. Such features of publishing systems are what geeks might call an anti-pattern because they encourage a bad practice of describing how something should look instead of what it means.

For instance, the element <h1> — and <h2>, <h3> etc. through <h6> — is used for headings in the document. Thus, you may be tempted to throw an <h1> tag in the middle of your document because you want larger text. This would be incorrect, however. The <h1> tag is used for the most important heading in any given document and search engines expect it to contain something equivalent to a headline. Instead, to increase the font size, use an element that describes the content and then use CSS to style it.

You are strongly encouraged to review in close detail the Codex HTML reference to understand how to make proper use of elements.

Most larger publication prefer to store their articles in XML because it enforces a greater uniformity. Codex, designed to foster diversity through unique or experimental article formats, finds a more comfortable fit with HTML. However, this carries the danger that your content will become an unwieldy rats nest as it grows in volume. The best hope to avoid that is through adherence to the standards and their guidelines for the semantic use of elements.

Nesting Content

One of the most useful features of HTML is it’s ability to nest groups of tags inside other tags, creating trees of elements of arbitrary depth. A complex article might have several sections, a sidebar of several paragraphs, block quotes and the like. This is easily accomplished in Codex by selecting text and using the Tab key. To remove a grouping that you’ve created, use Shift and Tab together.

This is one of the keys to unlocking the power for rapid-prototyping provided by Codex. For instance, we could easily simulate the card stack metaphor used for some articles on the website Vox by nesting content in a series of <section> or <article> elements on the page and adding a bit of styling to them.

You’ll notice that at the very top of each story there’s an extra tag input field that defaults to <article>. This let’s you change the tag that wraps all of the content or just add a few classes to it.

The Add Menu and Drag and Drop

There’s a menu next to every paragraph in the Codex editor and clicking it reveals options to add a paragraph, a block of raw HTML, or an index of stories. The menu can also me used to drag and drop the paragraph to another location.

Assets like images, videos and embedded articles can also be easily moved to a new location by dragging as well. As you drag things, a black bar will appear between elements on the page indicating where the item will be dropped.

Changing Style Sheets and Adding Scripts

While HTML provides the structure of your articles, CSS describes its appearance and JavaScript provides interactivity and other functionality. You can customize which bits of CSS and JavaScript are included in your page using the Style panel at the right side of the editor.

When you add a line of text to the assets box, it will load both CSS and JavaScript files associated with that name into your page. This is useful because most functionality requires at least a little bit of both languages.

You may list any number of assets, either from your publication’s proprietary code, the built-in themes or the special effects libraries. For instance, the built-in themes can be accessed by adding themes/heron or themes/raven. This code, like all that is available on the platform, lives in a Git repository that is linked to Codex.

Adding Share Buttons and Inline Assets

Codex gives you the ability to add share buttons wherever you chose to put them. To add a share button for Facebook, for example, you can simply type { facebook } inside curly brackets anywhere in your article, which creates a button like . If you’d like to add just the icon without a link to share, use { facebook-icon }, creating , which is useful for indicating links to other actions or pages on Facebook, like your publication’s homepage or an author’s profile page.

Some social networks allow you to suggest messages for the users sharing your article. You can customize the message used for each article inside its metadata or specifically for each button by using an argument inside the brackets like { twitter message="This is the suggested tweet" }.

Codex natively supports buttons for Facebook, Twitter, Reddit and email sharing, but you or the developers for your publication can add additional networks as you see fit. In fact, this same syntax can be used to add all sorts of so-called inline assets to your pages, including bits of HTML and SVG images, which are created using a syntax of tags similar to HTML. For an example of how to use SVGs on Codex, you can read about our fleurons.

The Importance of Good Metadata

Above the area where you actually write your story, you’re provided with a category for metadata which is information about the story that isn’t displayed on the page. This information is used to determine how the story will appear when shared on social networks and can be used to categorize your stories. Here’s some more information on the specific metadata fields.

Title This becomes the <title> tag in the resulting page and is used in the browser as the name of the window or tab. This carries great weight with search engines and is also used internally in Codex. Google recommends that this field not contain more than 60 characters, although far less will fit inside the typical browser tab.
Slug This is the last part of the URL that will be used for links to your story. URLs also carry a lot of weight with search engines, so you may think about using important keywords. If you don’t provide a slug, one will be generated from the title the first time you save your story.
Description This is very important. This field will be shown on social media when your story gets shared. It is also typically (although not always) used by Google as the paragraph that appears below the link in search results. The text here is also likely weighted heavily in search results, although the precise weighting is unclear. Google recommends the description not surpass 160 characters.
Suggested Social Message This is provided as the pre-populated shares on twitter or the body for e-mail shares. Facebook does not allow such suggested messages but neither is it used exclusively for Twitter. If it’s not supplied, the title of the article will be used.
Publication Date This is used internally by Codex and also provided to search engines. It will be filled automatically the first time you publish a story.
Location This is not used currently but could be used in coming versions of the platform to geolocate stories for readers or show a map. It’s recommended that you pick the location for the main events in the article or the location where it was written.
Custom Fields You can add any fields you want! Examples might be “tags” some other field that is not displayed in the body. These fields travel with your stories and can be accessed in JavaScript or used to build index pages for articles.

In order to include the publication date inside the body of your article you can use the word { date } inside curly brackets. This formats the publication date from the metadata like “January 1, 1970.” Of course, you could just type the date in the body of the article but then it would not be machine-readable and therefore won’t be accessible for search or sorting in chronological order.

To customize the way it’s displayed, you can specify a format string with an argument such as { date format="mmm d, yyyy" }, which would produce a date like “Jan 1, 1970”. Codex uses the node-dateformat library internally, allowing for a wide variety of formats.

This way of specifying the date also produces the correct markup, employing the <time> element.

Choosing Great URLs

Through the “slug” metadata field, Codex gives users an unusual amount of power over article URLs. This restores the ability to design short and useful URLs to the author, providing both opportunity and danger.