Markdown Basics
The Exocore utilizes standardized Markdown syntax, along with some additional extensions. Much of the content of this article covers existing markdown syntax used universally in plain text formatting. However, some syntax, such as wikilinks and images are particular to the Exocore.
The above is a level 2 heading, preceded by ##
and a space.
There’s nothing special about the way the Exocore processes headers— it’s just standard markdown. However, each header will render with an anchor link. If you hover over a heading and click the link icon that appears, the URL in your browser will reflect the section that you clicked. Now, if you copy that URL it will link directly to the heading that you clicked.
Heading levels
The above is a level 3 heading, preceded by ###
and a space.
Here’s some advice: Only use top-level headings (preceded by #
) for the document’s title. Aside from being markdown best practice, the Exocore takes your first top-level heading to use as the title of the page in the final rendered output. For intra-document section titles, use a level 2 heading. It’s for the best.
Examples of Wikilinks:
Here is a basic wikilink, pointing to other posts on this Exocore: <a class="wiki-link" href="/articles/exocore-executive-summary">exocore executive summary</a>
It renders like this: exocore executive summary.
It is written as the title of their corresponding markdown file, surrounded by double square brackets. However, in the final render they are presented by default as the page’s title. This saves you typing out the whole page title in your markdown document, and allows the Foam VSCode extension to suggest files as you type. Below you can read about how to change their presentation.
You can alias a link like this: <span class="invalid-wiki-link">[[chinese-ginseng-chicken-tonic-soup|this link]]</span>
if you don’t want to keep the title. Heads up— <span class="invalid-wiki-link">[[chinese-ginseng-chicken-tonic-soup|This link]]</span>
points to a recipe for Chinese ginseng chicken Soup.
You can also point to headers within a page: <a class="wiki-link" href="/articles/writing-with-exocore-syntax#wikilink-embeds">This wikilink</a>
. This wikilink points to a header further down on this page, by using a #
. Under that header you will find a different sort of wikilink— an embed. The content of another note is embedded within the current note. You can also point to a particular header within another note.
Check out the backlinks section at the bottom of any post, and you’ll find a list of every post that links back to it. Backlinks are automatically generated, and display all posts with links pointing to them.
Wikilink Embeds
The below text is embedded, using the same wikilink syntax as normal, but with an !
prepended. The full text of the linked note will be included. For example, here is an example of embedded note syntax:
![jade-post]
External Hyperlinks
Hyperlinks to external sites are not the same as wikilinks. A wikilink is a simple way to hyperlink to other posts on your Exocore without using the full processed URL as it is rendered online. A wikilink works locally in VSCode, allowing you to navigate between posts, and is transformed at render time to a web hyperlink, so that it always points to the correct page.
Configure exocore for personal use
Change your Username and Homepage
Navigate to /exocore/data/user.yml
. Open the file in any text-editor (e.g. Notepad or TextEdit) and look for user_name: Remilia Corporation
. Change this to whatever name you want to appear on the left sidebar.
Change your Homepage Content
In the same /exocore/data/user.yml
file, you will also see welcome_header
and welcome_subtitle
. These control the title and subtitle that appear on your homepage.
On the root folder you will find index.md
, this can be edited like any other article as your homepage with the addition of the title and header from the user.yml
file. Make sure you keep the following frontmatter at the top of the markdown file:
---layout: hometitle: home---
Change your Profile Picture
The profile picture that appears on the left sidebar is located at assets/img/pfp.png
, you can replace this file with any .png. Note that it will be resized into a square.
The social media card that appears when your site is linked on social media sites like Twitter, Facebook, etc. is located at assets/img/card.png
, you can replace this file with any .png. Note that a dimension of 1200x630 is recommended.
Make sure the site’s url is changed in /_config.yml
in the next step for this image to appear.
Change your Site’s Title and URL
Navigate to /_config.yml
to change the Title and URL of your exocore. All other settings can be left as is.
Change the Theme
The Exocore ships with multiple themes to choose from. Navigate to /styles.scss
and look for the line that says //Uncomment one of the following lines to choose a theme:
. To select a theme, remove //
from the line of the theme you want to try, and add //
to the previously active theme (“yotsuba” by default).
Optional: Password Protection
You can add simple password protection by going to your Netlify account, entering your site, going to Settings > Build & Deploy > Build Settings > Edit Settings
and changing Build commannd
from the default bundle exec jekyll build
to: jekyll build && npx staticrypt _site/index.html P@SSW0RD -o _site/index.html
This will password protect the homepage with P@SSWORD
as the password – you can change this to anything you’d like. Note that this will only protect the homepage, users will be able to directly link to any other page and have access to the whole site.
Move on to [[Using your Exocore]] for further guidance.
To create a hyperlink, use single normal parentheses around the URL you want to point to, and square brackets around the text you want displayed:
https://en.wikipedia.org/wiki/Parenthesis
[https://en.wikipedia.org/wiki/Parenthesis](https://en.wikipedia.org/wiki/Parenthesis)
You can alias a hyperlink by changing the text in the square brackets, like this:
Here’s some information about Hyperlinks.
[Here's some information about Hyperlinks.](https://en.wikipedia.org/wiki/Hyperlink)
Applying classes to a paragraph or image
Oh, by the way: You can apply the {:.right-aside}
class to create an aside, like this one. An aside floats to one side and other text wraps around it. {:.left-aside}
is also available for some variety.
Kramdown, the Markdown parser used by this implementation of the Exocore, has the ability to apply a CSS class to a paragraph by including syntax like {:.classname}
at the top or bottom of a paragraph. The class will be applied to the whole paragraph. The Exocore stylesheet includes a few general classes meant to be used for just this purpose, which you should feel free to add to.
The following classes are pre-defined in the Exocore stylesheet:
-
{:.center}
— Reduces width of paragraph and centers it for emphasis
-
{:.left-aside}
, {:.right-aside}
— Applies a border and floats to the left/right. Other text will wrap around it
-
{:.left}
, {:.right}
- Reduces width and places to the left/right (meant for images)
-
{:.border}
- applies a thin border
-
{:.shadow}
- applies a dark blurred drop shadow
-
{:.glow}
- applies a bright blurred drop shadow (produces a glowing effect)
-
{:.flip}
- flips the image (or text) horizontally
Tables
| You can | create a | simple table | like this. |
| ----------------- | ----------------- | ----------------- | -------------- |
| A new line | in markdown | extends the table | vertically. |
| A pipe | extends the table | laterally. | |
You can |
create a |
simple table |
like this. |
A new line |
in markdown |
extends the table |
vertically. |
A pipe |
extends the table |
laterally. |
|
For more options, check out the ‘advanced tables’ plugin in the sidebar. This plugin will assist you with spacing and syntax, and includes a powerful formula function, about which you can find information here.
Graphviz
For more complex data representation, Graphviz can be used in conjunction with the Exocore. Read more about Graphviz syntax here, and find a demonstration of the way it is used with the Exocore [exocore-workflow|here].
Footnotes are done with [^1]
, and look like this: Each footnote is an anchor link to the bottom of the page, with a return link attached. Notice the sidenote in the right margin, identical to the footnote.
All footnotes are also rendered as sidenotes. A footnote forms a commentary or citation best kept separate from the main text, and a sidenote is an easy way for a reader to access such commentary without breaking ergonomy by jumping up and down the page.
If you want to add multi-paragraph footnotes, indent your second paragraph, like this (see footnote at bottom).
[^2]: For longer footnotes, you may want to use multiple paragraphs.
Indent paragraphs to include them in the footnote.
You can put a footnote’s markdown reference immediately under a paragraph, like this, or clump them at the end. Either way, they will appear at the bottom in your rendered content.
[^3]: This footnote appears immediately underneath its referring paragraph in this document's original markdown, but on the rendered website it shows at the bottom.
Footnotes automatically form a numbered list, and can also be mapped by name, like this: [^named-footnote]
Inserting images
To insert an image, use the following syntax:
However, don’t bother remembering this syntax. the easiest way to insert an image is to use the Paste Image VSCode extension, included in Obsidian by default, which you will be prompted to download as a recommended third-party extension of the Foam VSCode extension. For MacOS, copy your image to the clipboard, and use keyboard command CMD + option + V
. You will be prompted to give your image file a name, and add it to the images folder in your Exocore’s top-level directory. Note: If you CMD+C copy an image from your desktop on a mac, it is not copied to your clipboard. Instead, open the image, and then use the same keyboard command.
You can insert alt text and a caption like this:
![This is alt text](/images/mouse.jpg)
*Insert a caption by placing italicised text immediately underneath the image*
The above snippet produces the below outcome:
Insert a caption by placing italicised text immediately underneath the image, with no empty line in between.
Embedded Code
To embed a piece of code so that characters are rendered verbatim, surround the code snippet with ``` on either side, like so:
#!/bin/zsh
cd ~/desktop/james-liao && bundle exec jekyll serve --baseurl ''
Use just one ` to embed code in the same line as the rest of your text.
Naming files
Don’t use whitespace in your filenames— instead, name-them-like-this. This way, titles are easily converted to URLs and the back end of the Exocore remains happy. This of course applies only to filenames, and you may title your posts how you wish.
That should be everything to get you started!
See more