Onboarding instructions (draft)

We were talking about onboarding instructions on Discord, and I opined a brief introduction should be… well, brief. I posted an example off the cuff, and someone asked me to post it here to share. Remember, newcomers need the few things they’ll do all the time, and they’ll get to the rest when they need it. Let’s beat on this a little, and maybe the devs can add it so newcomers always see it right away.


  • Graph is your collection of data, including your journal, pages, tags, and assets. You can view your graph as pages or a connected graph.
  • Assets are usually graphics.
  • Blocks and entries are the same thing, a single paragraph or outline entry.
  • Tags are a way to group both pages and entries.


  1. Collect your thoughts of the moment onto the daily journal page.
    Use indents to group related thoughts, and Markdown for highlighting.
  2. Tag anything you want to reference in the future.
    Use either #tagname or [[compound tag name]]. Let Logseq build most of your pages for you.
  3. Use / to insert special stuff. It pops up a long menu of choices.
    Typing a couple of characters narrows down the choices (for example, /to shows only entries containing that string). Pick one of the choices to make it active.
    1. /TODO, /DOING, /LATER, /NOW, and /WAITING create checklist items with the label shown.
      • You can click on the label to toggle between TODO and DOING, or NOW and LATER.
      • Check the box to mark the item completed (this makes it DONE).
      • You can tag your checklist items, too.
    2. Use a query to collect your entire to-do list into one place.
      • For example, {{query (task todo later waiting)}} fetches items that you marked as inactive.
      • A default query shows your current DOING and NOW items.
  4. Use the Favorites (Contents in older versions) page to create links to pages you revisit often.
  5. If you need to create a page, use [[double square brackets]] (yes, creating a tag creates a page). If you want the page to have a tag different from the title, the first block should contain only tags:: tagname.
  6. There’s lots more to Logseq. Click the ? icon in the lower-right corner for more extensive help.
    The last entry, Discord community, has a wealth of first-hand experience.
  7. Have fun with it!

I’ve deliberately left out a ton of stuff: more advanced task management, PDF annotations, plugins, importing from other tools, document mode, and especially advanced queries. :smiley: The goal here is to get people comfortable with using the basic functionality, and they can learn about all the other goodies when they have a need. But if I’ve left out something crucial, let’s hear it!


This is great!

Just throwing in my six cents:

Not an issue with the onboarding, but more of a UI copy choice. “Graph” is too technical a name for what is actually a folder with files. Furthermore, considering that there’s also the “Graph View”, I think this is bound to create confusion.

This needs unpacking.

  • For a complete beginner, we should expressly mention Tab/Shift+Tab and drag-and-drop.
  • Markdown basics should be a whole section by itself. Further down, of course, because we don’t want to overwhelm them with syntax right off the bat.

IMO, this forum would be a better entry point, as far as actual support goes. It’s very easy for a newcomer to feel overloaded by all the channels and conversations on Discord; it’s easy for a question to go unnoticed or unanswered. On the other hand, answers on the forum are much easier to retrieve and more likely to help others. Of course, Discord is great for chit-chat, brainstorming, and, well, socializing, which is also very important, so it should be mentioned.

1 Like

Thanks for the feedback @macedotavares !

I agree about graph — the problem is, that’s what it’s been called since before I found Logseq. A sentence or two would be enough to clear it up, I think.

Graph is your collection of data. There’s also a “graph view,” that displays your entire collection as a set of linked nodes. In the end, it’s a collection of files in a folder.

For Markdown, which variant does Logseq use, GFM? I think it should be sufficient to link to a good tutorial for that variant. A minimal set of instructions, I believe, is key to helping newcomers feel comfortable — but that’s not to say we shouldn’t link to more info where it’s going to help, of course.

Finally, I chose the Discord because:

  1. That’s where the “community” link goes.
  2. It’s only been a few weeks since I realized this forum exists, and I’ve been using Logseq for five months. :laughing: I’ll log a Github issue to add this forum to the help links.

Thanks again! BTW, my 12 year old came in one evening, looked at my screen, and asked “Is that Discord?” :rofl: I guess the olds aren’t supposed to know about it…

really appreciate these instructions and the onboarding video i saw today Logseq onboarding event 2 - YouTube . however i think there are some assumptions about a base line level of knowledge that might hurt a broader range of first time users. here is a very rough mock up of the kind of thing i feel like might be useful on first launch:

First Screen:

Second Screen:

Third Screen (once tool tips are closed)

navigation basics would then introduce moving between block/page view, creating new pages, links, sidebar etc.

once there’s a feeling of - this is cool i wanna learn more–the above sort of overview, or the info in the above onboarding video @ 27:00 might seem more intriguing and like ‘new tricks’ rather than dense abstract information.

i know this is just one way of learning and different people learn in different ways. but i feel like for a lot of people out there poking around, being able to play is an important first step before wanting to read and learn the more theoretical stuff.

other people might really like the theory stuff first but i think for people like that there’s a lot out there they’ll already be diving in to before opening the program and they’ll breeze right through this intro stuff. anyways just one idea - hope it’s helpful

1 Like