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
- Add a headline and byline
- Upload and layout images
- Change the story’s style sheets
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.”
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.
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.
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
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.
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
full-width. You can read more about how to use these classes from the built-in themes further in the documentation.
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.”
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
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.
- We would look back on the present and think of it as a dark age when human beings lived only on Earth.
- When we have a factory in space, any unavoidable pollution that it produces can be discharged into space.
- Here on Earth, most people, especially those in power, are far more concerned with the immediate threat from other countries than they are with the possible dangers to civilization as a whole.
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
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.
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:
Make the first paragraph of the story a
introto match the original text and add a dropped capital on the second paragraph with the
dropcapclass. You can read more about the classes built into the themes further in the documentation.
Swap out the image at the top of the story and position the headline on top of it, along with some responsive cropping and the
full-windowclass to make it fit the size of the browser window.
- Add some transitions to the pull quotes and images so they fade in as the user scrolls down the page.
- Add some icons to prompt readers to share the story on social media.
- Make the images stick to next to the text in different sections. Or keep them in a fixed position.
- Add a photo grid that shows more of the NASA renderings.
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