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

Codex Quick Start

Let’s dive into the Codex editor by running through the steps to publish an article. In this tutorial, you’ll learn the basics, including how to

As a demonstration, we’ll be publishing the transcript of a lecture given by Isaac Asimov in 1985. There’s a print copy of the lecture as published by NASA available online, but it’s difficult to read and enjoy in that format. The final product will look like this when we’re done: https://codex.press/asimov/cosmos-demo.

Step 1: Create a new article

Begin by starting a fresh article at https://codex.press/edit/article/new. Where it says “Title” at the top, go ahead and type in “Our Future in the Cosmos.” This title will appear in the tab bar of the reader’s browser, so the shorter the better.

Copying the text from the PDF produces all sorts of minor errors from scanning, but we’ve gone ahead and corrected them for you in the text below. Click the button that says “Copy” to copy the text and then paste it into the new article where it reads “Your article here.”

Copied to clipboard!

Step 2: Style the headline

Codex works by putting different bits of text inside HTML elements. This is actually how the entire web works, so as you learn Codex, you’ll be learning skills that translate to other projects.

Right above the first line in the document you’ll see a grey p. To make our first element, let’s type h1.hed in that field.

In the Codex editor you add a headline by choosing an HTML tag.

This does two things. It tells Codex to put the headline inside an HTML <h1> tag and adds the class name hed, which is used internally in Codex to signify the main headline of an article. These two things combined—along with CSS, the code used for design on the Web—change how the text appears on the page. They also crucially add meaning, so that search engines and other bots (and even other people collaborating with you) know exactly what this text is supposed to be. To learn more about HTML elements, please read the handy reference in the Codex documentation.

Step 3: Use the preview

Let’s see what we’ve got so far. Hit the preview tab on the right to check out our work in progress.

Preview how your article will look on mobile devices as you write it.

This is a live preview of the document, so as you type it will be updated in real time. Let’s go ahead and add more HTML elements to finish marking up the text and we’ll see how that changes the finished document. Add address.byline right above the name Isaac Asimov. This uses the HTML element <address> which is what the web standards tell us to use for a page’s author.

In order to view the story in a separate tab just as our readers will see it, we’ll need to give it a URL. At the top of the document, you can add a slug to your story which is what will become the last part of the URL. You can pick “asimov” or “cosmos” or something simple then hit the save button. You can now open the story in a different tab just by visiting the URL, which is a combination of your account name and the slug, like https://codex.press/your-name/slug.

Step 4: Add some images

The article still looks very plain, but some images will help. We’re going to be adding some delightful 1970s renderings from a different NASA project, which you can download here: https://settlement.arc.nasa.gov/70sArtHiRes/70sArt/art.html It’s best to select the highest resolution because Codex will automatically resize the images for different devices. You can upload them to Codex by dragging the downloaded files from your computer directly into the editor.

Upload an image by dragging it onto the browser.

By default, the images will stay in the center column at the same width of the text, but we can change their location and size by adding the classes left, right, or full-width. You can read more about how to use these classes from the built-in themes further in the documentation.

Adding classes to images lets you control their size and position, among other things.

Step 5: Add some captions

Let’s add a caption on the second image that tells the reader about their source. Something like, “Renderings of space colonies made for a 1975 NASA initiative, courtesy NASA Ames Research Center.”

Adding a caption to an image in the Codex editor.

Step 6: Add some inline tags

There are a few points where we need to add HTML tags inside the paragraphs of the story. You can do this by selecting text and using the menu that pops up above it. In particular, at the end of the story we’ll want to highlight the structure of the question and answer section in a way that makes it easier to grasp visually. A quick look at the HTML reference shows us that the <b> tag is the most semantically appropriate way to do this.

Asimov mentions his book I, Robot and it would be ideal to style this citation correctly with the <cite> tag. In addition, he twice refers to the bacterium E. coli and we might put that Latin name in italic with the <i> tag.

Step 7: Add some pull quotes

Oftentimes readers like to skim a story before deciding to dive in and begin reading. A series of great pull quotes can highlight for these readers what they’ll be getting, as well as add some more visual interest to the page. Here are some great turns of phrase from Asimov that you can add to the the text.

Paste the text into the story in a new paragraph and then type “aside.pullquote” above the paragraph to use the HTML element <aside> and the class pullquote. To signal to the reader that this text is outside the main reading flow, we can float the paragraphs to either side by adding the classes “right” or “left.”

Step 8: Add an editor’s note

Now we’ll also want to add something that gives a quick introduction to what this story is all about. The built-in themes offer styles for this purpose with the class editors-note. Here’s a short introduction that we can use:

Celebrating it’s 25th anniversary in 1985, NASA invited science fiction writer and scientist Isaac Asimov to join a lecture series at The College of William and Mary. The following is an edited transcript published by the agency.

Asimov details the reasons he believes humans will create large cities orbiting the Earth, predicting the gravity of climate change and the current space-colonization frenzy more than three decades ago.

Instead of adding the class to both paragraphs separately, let’s group them together into another HTML element that will contain both of them. Select a bit of text from both paragraphs and then hit the Tab key to group them. We can then add the editors-note class to the resulting <div> element.

Two or more paragraphs can be grouped inside a containing HTML element with the Tab key

Step 9: Change the style sheet

The fonts and colors for this story default to Codex’s Pigeon theme, but we are free to pick something a bit more interesting. In the Style menu on the right of the story, go ahead and change where it says themes/pigeon to something like themes/raven/celtic. You can read about our default themes and pick your own further in the documentation.

Changing style sheets to swap out the default theme for something a little more interesting.

Step 10: Add metadata and publish

Before you publish, be sure to give the article some proper metadata, which is used to help people find the story through search engines and social networks. In the description field, let’s type the following: “A 1985 lecture from writer Isaac Asimov on the reasons that humans will colonize space and the benefits it will reap.”

Now click the publish slider and the save button. That’s about it! The final product should look like this: https://codex.press/asimov/cosmos-demo. If you’re interested in going further with the Asimov article, here’s a few more things you could do:

Once you learn to do all of the above, the article might look something like this: https://codex.press/asimov/our-future-in-the-cosmos