Corilla First Impressions Published using Corilla

Corilla First Impressions

Corilla features I'm excited about

I've been super excited for Corilla to release their beta. They have several features that I have been wishing to use for years.

This particular set of features will make it particularly attractive to document open source software, since you don't need to download or compile or have a viewer for anything the way you do with Sphinx or Mallard.

The only thing you would need to contribute documentation is a web browser and an invitation to the team, and then your topic is as valid as anyone else's.

The emphasis on topics instead of books also makes it easier to create conditional documents. If you're writing for a product that has 8 modules, and someone only purchases 3 modules, instead of making them wade through the documentation for the 5 they don't have, we'd just drag in the core topics and the topics for the 3 purchased modules. I worry how this will scale out to thousands of topics, but I have faith that this use case is on the roadmap.

My feature requests for Corilla

Corilla is super at several features I've been wanting for years, but before I can use it as a replacement for my existing tools, I'd like to have these features, or at least a timeline on when we would get them:

Note: I may be missing some things it can actually do because I'm using the wrong flavor of Markdown. A really great cross-team tool will accept as many flavors of Markdown as humanly possible, and not be strictly-typed to one (unidentified) flavor.

My guesses

Just like a trailer for a movie, a beta for software gives you a lot of room to guess and speculate and get excited for a new product.

Roadmap

Here are my guesses for features that we'll see relatively soon in Corilla's development:

Monetization

It costs money to run servers and to hire teams. Since Corilla is not an (obvious) offshoot of any big company, nor have they been acquired yet, we have to assume they have a plan for how to keep the lights on. Here are my guesses at what they will charge for, above the free platform.

Corilla Markdown

Update! I have found out what they are using! It's a Markdown variant called Markdown-it, and you can find the documentation here: https://markdown-it.github.io/

I'm not sure what Markdown flavor Corilla is using. If they told us, it's not obvious. And it's not Github-flavored Markdown, which is the one I know best. So! Let me show you what I've figured out.

/ The slash character before a control character allows you to show the control character without it being interpreted.
For example, without /, this:
--
would make the preceeding paragraph a heading. There is currently only one level of heading, so any number of - under a paragraph (up to four) will give you the same heading.

One hash /#

Two hash

Three hash

Four hash

Five hash
Six hash

Six levels of heading.

Two levels of bullet

/----
Four ---- will produce a hard rule if they are on their own line.


Text styling

_ italic
** bold
The text emphasis levels (rendered as italic and bold) can use either _ or *. You have to "close the tag" by putting control characters after your emphasized text.

Code styling

Code! Markdown-it has three (and a half) different types of code described:

Inline code---

Use the /' or "backtick" character. That is the one that is usually the alternate of ~, not ". You can use it to embed a code indicator within a line, like a span tag.
Find your file in C://place.thing

Indented code

Use a double backslash // to indicate several lines of code. This method depends on using empty lines in the markdown, so be careful if you have something stripping those out in your CSS.

// Some comments
You need an empty line above
and below to make this work
So much depends
on invisible carriage return
among the white chickens
line 1
line 2

Block code "fences"

Use the triple backtick /``` at the beginning and end of your code sample. This is probably more suitable for long stretches of code you don't want altered, like a config file. This one also relies on a frame of empty lines.

I was a child
And she was a child
In the kingdom by the sea
line 4
//commented text in the code still works
Edgar Allen Poe was the original goth
The backticks act as escape characters
### see? no heading even with hashes

Syntax highlighting

This is the half. It looks like it's not rendering the color/syntax the way the example on Github does. Still, I'm so excited to have proper code citations, I don't even care. To put in syntax highlighting for when it does work, wrap it in the triple-back tick, followed by the abbreviation for the language you're using, so it knows what to higlight. This example has ```js as the first line.

var foo = function (bar) {
  return bar++;
};

console.log(foo(5));

Bullets are simply * and a space at the start of the line.

Numbers are also only specially formatted if they start a line. They must have a period and a space after them to be rendered as an ordered list.

  1. You ain't nothing but a hound dog.
  2. Crying all the time.
    Indented explanation.
  3. You ain't never caught a rabbit.
  4. You ain't no friend of mine.

What's interesting there is that all my number as I write them are actually "1. ". Once the Markdown recognizes an ordered list, it will keep using it until there are two blank return lines (paragraph) at the end of it.

Links! There are two kinds of links:

To go to a URL, you're going to type [www.corilla.com]. The brackets are what make the magic. Whatever is in the brackets will appear.

If you want to have a link that is easier to read, put the name it (parenthesis) immediately after the brackets, like so: Agile Crafting. Be sure to put the HTTP in if you want an external page, or Corilla will assume you're linking to another topic in your collection. Other Markdown flavors support further features like descriptive text, but I haven't found it in Corilla yet.

To add an image, it must be hosted on a site. You can't refer to images that are only on your computer. The syntax is /!/[image]/(URL) without the slashes.
Minion

Bugs

Not all of these are true bugs, but they are moments in the experience where I was confused or wished for something different.