Get started with Athens Research

My friend and Netdata colleague Odysseas Lamtzidis (@odysseas_lam) recently told me about Athens Research, the company behind Athens, which is a knowledge graph for research and note-taking. It's also free and open-source under the Eclipse Public License.

I've been using Obsidian for close to a year, and was an avid Notion user before that. I'm familiar with some of the recent developments in this space. I'm by no means an expert in organizing a personal knowledge base, but I do have a curiosity.

There's no better way to learn than to teach, with a little big of lag between the two. What better way to learn this new tool, and hopefully make the Athens ecosystem a little richer than I found it, than a Get started with Athens guide?

I won't cover installation here, and this won't be an exhaustive list of Athens' features. Think of it like everything you need to have a successful first 15 minutes with your new knowledge graph.

The daily note

When you first get into Athens, you're greeted with a single note titled with today's date. This is your daily note. How you use this daily note is up to you. No matter where you go in your knowledge graph, today's daily note is always a click away with the calendar icon in the top panel.

I tend to use daily notes for keeping some unstructured thoughts about my day, checking in throughout the day to add some updates. I take notes about anything interesting I find or organize my thoughts on a specific subject on separate pages. More on that later.

Write in blocks

You might notice right away that as you type into your daily note, Athens highlights the line you're working on with a slightly darker gray color. This highlighted area is a block. Blocks can contain plain text, styled text using a subset of Markdown syntax, TODO checkboxes, and more.

On one level, blocks operate like paragraphs in Markdown or a Google Doc. When you feel a natural break in your writing, hit Enter to start a new block. Or, type Shift+Enter to start a new line within the same block. Continue as you would with any other writing or note-taking app you're familiar with. You don't have to think about blocks any further than that.

But blocks are more than a container for text. You can move entire blocks around as you see fit, and you can reference one block from within another, creating a connection between them. More on references in the next section.

To move a block, click and hold on the gray dot to its left, then drag to any other location on the page. As you drag, a blue line shows you where the block will drop if you release.

Blocks can also be nested inside of other blocks by dragging further to the right. Once you've nested some blocks, collapse the parent by clicking on the chevron ⌄.

Create links and references

Next, create a new page by clicking on the Find or Create a Page button in the top panel, or typing Ctrl/⌘+K. Type in the name of the page, then hit Enter, or click on the area that says Create Page:.

Now that you have two pages, start building out your knowledge graph by creating your first link.

Type [[ followed by the first few characters of your daily note. For me, that's April 24, 2021. When that page shows up on the dropdown, click it to finish the link. Hit Enter to create a new block, and you'll see that the link is now blue, which means it's active. Click it to navigate to your daily note.

In Athens, links are bidirectional, which means they now reference each other. Beneath every page you'll find an area titled Linked References, which is where you can see all the pages that link to your current page.

Next, create a reference between blocks. Type (( followed by the first few characters in the block you want to reference. Find it in the dropdown and click on it to create the reference. Now, if you click on that reference block, Athens zooms you in on that block.

Links are great for creating immediate connections between pages, while references are perfect for adding direct quotes from something you've already written or collected.

Move around your graph

Athens doesn't organize your pages into a hierarchy of folders and files, like you see as you explore the files on your system.

Instead, Athens expects you to create a knowledge graph using links and block references. Instead of relying on this intricate hierarchical structure, which you'll need to consistently prune and optimize the more complex your knowledge graph gets, Athens works best when you create lots of links and references between your pages.

Think about how you get around Wikipedia. Do you browse an index of every article? Of course not. You read a page, see a link to something else that's related or of interest, and continue exploring. Instead of a hierarchy, it's a knowledge graph.

Athens works the same way. You're responsible for creating the knowledge graph with links and references, and then Athens gives you a few ways to navigate around it.

The most obvious way to get around is the Find or Create a Page button, or using Ctrl/⌘+K.

The calendar icon takes you to today's daily note. The page icon takes you to a list of all your pages. There's also back and forward buttons to navigate between your most recent pages.

Click on the three dots to the left of any title to open a menu, which lets you add that page to your Shortcuts.

If you hold Shift and then click on any link, it'll open up in the right sidebar, which can contain any number of open pages. This is useful if you're pulling information together from multiple notes and want to keep the references open without having to switch between them with any of the aforementioned buttons.

Export single pages

As of the last update, there is no way to export your pages to another format, even plain text. If you copy-paste an entire page into another editor, like VS Code, you'll notice that every line begins with a - character.

Let's say you want to draft a blog post in Athens, then convert it to Markdown once you're ready to publish.

Select the entire page with Ctrl/⌘+A, then paste into your text editor. I use VSCode, and while the instructions vary between tools, the idea works anywhere.

Next, open up the find panel, and type - into the find field. Type \n, which represents a new line, into the replace field. Make sure you click the Use Regular Expression option (.*). Use replace all to remove every one of those pesky hyphens. This bit of regex won't do anything smart with nested blocks, but that makes sense, given that there's no concept of nested paragraphs in Markdown.

What's next?

Now that you understand the basics of Athens, there's an almost overwhelming number of ways to actually use it.

Start small. Take some notes about your thoughts today. If there's anything in those notes that feels like it could be expanded upon, create a new page and link the two together. Click on the Open Graph button, which looks like three bubbles, to see the budding connections.

Be sure to give the project a star on GitHub, and poke around the discussions to learn some new tips or see what's up next in their development process.

There's plenty more to learn about using Athens that I need to figure out myself, so I'll keep this guide updated with anything else I think is essential to having a successful first 15 minutes. Beyond that, I'll create separate posts covering the most interesting new finds.

If you have questions or corrections, send me an email.

Further reading & resources

• Athens docs
• @AthensResearch
• Athens Research on GitHub
• Athens Research on Discord
• Athens cheat sheet