├── gtd-design-goals.norg ├── indentation-changes.norg └── syntax ├── inline-link-targets └── index.norg ├── multi-word-tag-parameters └── index.norg ├── multiple-choice-questions ├── final-ideas.norg └── initial-ideas.norg └── zettelkasten └── zettelkasten.norg /gtd-design-goals.norg: -------------------------------------------------------------------------------- 1 | * A description of the UI implementation within Neorg's GTD 2 | 3 | *** Most Important Design Goals 4 | 5 | - ZERO FRICTION - user interfaces should provide as little friction as possible when capturing a note 6 | of any kind. 7 | - Fast response times - the interface should be very responsive and database operations should not be felt. 8 | - Dynamic data - notes and ideas should be representable in many formats - the form of a list, a calendar, a graph. 9 | - Ensure that migrating from "small" to "larger" thoughts is unobtrusive. 10 | - Provide several calendar views and graphs to visualize data. 11 | - All data should be stored in plain-text `.norg` files, such that it can easily be version controlled and sent across 12 | devices. 13 | - Understand the nuances and pain points of other note taking solutions (points back to the "zero friction" bullet point). 14 | 15 | * Step 1: Capturing 16 | 17 | The capturing process involves having an idea or new task and writing it down somewhere where it can be 18 | reviewed later. 19 | 20 | An important thing to note is that the process of capturing *does not necessarily imply* the process of annotating. 21 | Annotating is adding metadata like contexts, timeframes, associations (unique to Neorg) and projects. Those are 22 | part of the Next Actions ontology, and are discussed later. They /can/ be also part of the capturing process (something 23 | we call `preliminary information`), but for most cases they are not a requirement. 24 | 25 | The capture mechanism is bound to `` by default. It can be executed on /any/ file, 26 | including non-norg files. 27 | 28 | *** The User Interface 29 | 30 | The user interface for capturing a note should be hilariously simple at first glance. 31 | All the user should see is a text box with a prompt to press `?` for more information. 32 | The expanded information should include the basic capture syntax. 33 | 34 | The most basic capture syntax includes: 35 | %TODO: add more syntax% 36 | - Regular text - the normal content of the captured note. 37 | - `#work` - a context, some circumstance that you can attach to the note itself. 38 | - `@jeremy` - an association, an entity that is bound to the note in some way. 39 | - `!1` - urgency, starting from 1 to infinity. One is the most urgent. 40 | - `&tickler` - binds the content of your note to a specific {* ontologies}[ontology] alongside the default `&inbox` ontology. 41 | - `~1{y[ear]|mo[nth]|w[eek]|d[ay]|h[our]|m[inute]}` - the estimated amount of time you expect the task to take you. 42 | The content in square brackets is optional. Recommended to give yourself a rough estimate without setting a specific 43 | due date. 44 | 45 | *** Default Captured Information 46 | 47 | When pressing the "capture" keybind, a default collection of information should be collected and stored 48 | alongside the note, ready for the user to see when they are going through the processing phase. 49 | 50 | This set of information includes: 51 | - The exact date (down to the minute) the note was captured. Seconds should be omitted, as we would like to 52 | minimize cognitive overhead. 53 | - The name of the file and the line number where you got the idea - this should in most cases help as a context 54 | where you got your "aha" moment. 55 | 56 | *** Extra Captured Information 57 | 58 | The user should be able to highlight some text in their current buffer before pressing the capture keybind 59 | to attach the text (with appropriate syntax highlighting) to the note. 60 | 61 | *** The User Experience 62 | 63 | Punctuation tends to be a serious giveaway to the "tone" of a note. It could be sensible for Neorg to notice 64 | that a note ends with a question mark, and therefore should by default put the note inside the `maybe/someday` ontology. 65 | If the user during the processing phase changes their mind and does not decide to throw the item into the someday ontology 66 | then the item can be happily pulled from under the rug. 67 | 68 | *** Interesting Details 69 | 70 | If a note contains preliminary information, it will first be put into the appropriate container as a "volatile" task. 71 | It will behave just like any other task or idea, but it will /still/ be presented to the user during the processing phase. 72 | It's during the processing phase that the user can then fully commit to their initial decisions or alter the metadata of the 73 | task to repurpose it and move the task to a different container. 74 | 75 | *** Other Capturing Mechanisms 76 | 77 | Apart from this "quick capture", it would also make complete sense to support whole file captures, external resource captures 78 | (URLs, PDFs), etc. each with their own UIs. 79 | 80 | * Ontologies 81 | 82 | Before any further explanations are made it's important to understand 83 | /ontologies/ as a concept. This concept is general and exists in the whole of Neorg, but is extensively used 84 | within the GTD implementation. Think of an ontology as a container with some 85 | distinct properties. For starters, a single ontology contains any number of 86 | elements of the same type. The type consists of the following: 87 | - A text field (required) 88 | - A `derives` clause (optional) - this merges the current ontology with another template ontology. 89 | Useful to derive e.g. a `calendar` ontology which will force you to provide all of the data necessary 90 | to display a calendar. 91 | - A `display` clause (required) - how to display the data in the ontology, can be one of `list`, `graph`, `calendar`, `table`. 92 | - Any set of keywords: `key \: Date|Text|File`. Some keywords can be marked as required, 93 | while others optional. 94 | 95 | In Neorg, *every GTD list is simply an ontology*. This includes the inbox, the next actions, tickler file, calendar, you name it. 96 | Neorg binds your captured task to an ontology under the hood. Moving a task from the inbox to the next actions list is equivalent 97 | to changing the ontology from `&inbox` to `&next-actions`, and letting the type system verify if all variables and data are in the right 98 | place. 99 | 100 | *** The Power of Data 101 | 102 | Given ontologies are just generic containers, their data can be bent at the user's will. Data can be displayed as tables, lists, calendars 103 | and others given the correct queries. 104 | 105 | This means that, unlike GTD's lists, ontologies are not as tightly intertwined and are more flexible as a result. This means that any specific 106 | list (e.g. the calendar) can be duplicated or its output modified (you can have several different calendars which are just 107 | different ontologies with their `display`:s set to `calendar`). 108 | 109 | The GTD implementation in Neorg works because Neorg's GTD provides a *default set of ontologies* 110 | (with appropriate names like `&inbox`, `&calendar` etc.) crafted to mimic the GTD workflow in the most efficient way possible. 111 | These ontologies are simply registered within the Neorg environment and are used appropriately. 112 | 113 | * Processing 114 | 115 | Processing is a very important part of your workflow. It involves going through each capture in the inbox 116 | and deciding what the next course of action for that task should be. You perform processing whenever you have some spare time 117 | to do some side tasks. 118 | 119 | *** Processing View 120 | 121 | There are a few ways you can process tasks, these are "one by one", "list view" and "calendar view": 122 | - One by one - self explanatory, displays one task at a time, allowing you to make a conscious decision 123 | for each task. Packed with one-key keybinds for most tasks (send to maybe/someday ontology, send to tickler file, archive). 124 | - List view - for when you know you had some important things to do but do not want to sift through every SINGLE capture 125 | you've made. Most urgent tasks should be displayed in red. 126 | - Calendar view - since tasks are first sorted by urgency and then date created (ascending), it is also possible to display your 127 | thoughts in the form of a calendar. Especially useful if your tasks are often time sensitive. 128 | 129 | The order in which tasks are presented should be: 130 | - Most urgent first, or 131 | - Oldest first 132 | 133 | *** Types of Actions 134 | 135 | Depending on what you would like to do with the task you may opt for a set 136 | of different actions: 137 | - Add to the `maybe/someday` ontology, e.g. "learn Ithkuil". 138 | - Convert to an `action` and move to Next Actions. By `action` we 139 | mean an actual PHYSICAL thing you can do, instead of a hypothetical. E.g. 140 | "plan cake lottery" -> "e-mail Arthur and Camille and remind them to bake 141 | their cakes". 142 | - If the task can be done in 2 minutes, DO NOW - the editor will enter a 143 | state of "doing a task", and Neorg will remember across sessions that a 144 | task is still in the process of being done. 145 | - Move to Next Actions. 146 | - Delegate to a timeframe/date - this will open up the calendar view with 147 | all your other tasks and allow you to select when you want to assign the 148 | task to be done. 149 | - Delegate to "waiting for" ontology - if your task is being blocked by another person or 150 | task you may move it to the "waiting for" ontology. If you have your associations and tasks 151 | set up correctly Neorg will also be able to auto-detect when this task is no longer being "blocked". 152 | - Move to a project (if the project doesn't exist, it will be created, else the task will be appended 153 | to the end of the project). 154 | - Archive the task. 155 | - Place the task in the trash. 156 | 157 | *** "Waiting for" 158 | 159 | Talk about automatic unblocking of a task if your associations and tasks are set up correctly. 160 | The unblocked task is moved back into the inbox. 161 | 162 | Also talk about how waiting for's can have expected unblock dates (expected due dates) 163 | as well as expected start dates just like a regular task. Neorg will then notify you if that 164 | task is overdue or was done faster than you expected (useful if you want Neorg to tell you that 165 | coworker Jimmy has been slacking on the side project for the past 2 weeks now). 166 | 167 | *** UI/UX 168 | 169 | - Each type of action should have a single mnemonic keybind bound to it regardless of the processing view. 170 | - The default view should be a popup box in the middle of the screen with basic actions. Pressing `?` 171 | should display help related to that action. 172 | - The user should additionally be able to press the `u` button to undo the last action and place the task back into the inbox. 173 | 174 | %TODO: Describe UI for the other views% 175 | 176 | *** Common Metadata Operations 177 | 178 | When processing your tasks you should also verify preliminary metadata or assign metadata to your tasks. 179 | 180 | During this stage, you may press any of the keybinds to apply any metadata. Press `C` to add a space separated list 181 | of contexts, and press `` to apply. Press `A` to assign the note to a specific association. 182 | 183 | Contrary to other GTD implementations, the user should also be able to press `Es` (estimated start date) or `Ed` (estimated due date) 184 | to set a fuzzy date for when they expect the project to be complete or started. Not every task has a strict deadline, and you 185 | definitely do not want to see tasks that actually *do* have a deadline shown with the same urgency as tasks that only 186 | have an estimated deadline. 187 | 188 | **** CONTEXTS vs ASSOCIATIONS 189 | 190 | A /context/ is a general tag that you apply to your note - this includes the tools you might need to complete the task, 191 | where the task needs to be completed, or a category that your task falls under. 192 | 193 | An /association/ is just like a context but it has *permanent metadata* attached to it. This is especially useful for people 194 | or locations. You may create an association to a coworker (think of it as a profile) with their name and surname 195 | as permanent metadata. Then, when you're in a meeting with them, you may bring up your list of associations with that person 196 | to see what you wanted to discuss with them. 197 | 198 | * The Next Actions 199 | 200 | The Next Actions is the list of items you visit when you're *going* to get 201 | things done. Instead of hypotheticals or things that need to be expanded on, 202 | you go through each item in the Next Actions ontology and get each item done. 203 | This ontology displays the general items of the Next Actions as well as tasks 204 | with upcoming due dates. By default, all items in a Next Actions have an 205 | urgency of 10. Items that are part of the calendar (with marked due dates) 206 | have their urgency equal to the amount of days left for the task (remember, 1 207 | is the most urgent). 208 | 209 | The Next Actions is displayed in whole, allowing you to choose what you would like to work on first. Items with 210 | the highest urgency are displayed first, with every other item sorted by the estimated time that task will take, 211 | otherwise by date created. 212 | 213 | *** Facilities for Time Management 214 | 215 | When you press `` to begin working on a task, Neorg enters a "task 216 | pursuit" mode. It will provide live information about the due date, the time 217 | spent daily on the task, completion rate (if you are working on a project). 218 | The `:Neorg task` command should display this information in a single popup, 219 | with the following abilities: 220 | - Mark the task as complete. 221 | - Temporarily pause - pause the current task (to go eat lunch, sleep, or 222 | perform other intermediary activities). Closing all Neovim/client 223 | instances will automatically signal to the GTD process to pause the task. 224 | - Cancel the task (with a reason) - equivalent of moving to the archive. 225 | - "Change your mind" - move to the `maybe/someday` ontology. 226 | - Postpone the task (to a different date). 227 | - Block the task (move to the "waiting for" ontology). 228 | 229 | *** Pomodoro Integration 230 | 231 | This wouldn't be the job of GTD itself, but a pomodoro plugin could hook into the currently active task, 232 | provide metrics like "if you spend 40 minutes a day on this task it should be complete by x" and the usual 233 | pomodoro features. 234 | 235 | *** Statusline Integration 236 | 237 | Neorg should provide statusline functions to display GTD progress, tasks left and other important bits of 238 | information. 239 | 240 | * Maybe/someday ontology 241 | 242 | The m/s ontology is for thoughts or ideas that you are unsure about or do not have time to currently pursue. 243 | They do not clog up your Next Actions nor the inbox, allowing you to keep the things you actually have to do 244 | clean. 245 | 246 | Items are moved here during the capturing phase or during the processing phase. The contents of this ontology 247 | is reviewed ideally at the end of each week during the {* review process}, ensuring all of your cool ideas 248 | are still under your consideration. 249 | 250 | Contrary to other GTD implementations, the m/s ontology *also allows you to have projects within it*. It's common 251 | to have an idea or concept that you might do someday, but you would like to have planned out in advance. It's also 252 | an interesting way of procrastinating I guess :p 253 | 254 | After a task receives a defined or estimated due/start date it will then be moved into your regular `&projects` 255 | ontology where you can proceed to work on the project. 256 | 257 | * Archive 258 | 259 | The archive is where tasks that have been put down are placed. They're not entirely deleted and still 260 | have a task ID, therefore they can still be referenced, but they are *not allowed to have any time-sensitive metadata*. 261 | 262 | Any other metadata is retained, should the item be unarchived in the future. 263 | 264 | For GTD `1.0.0`, the archive should be as simple as this. Just a container for tasks/notes that are no longer of interest. 265 | In the future the capabilities of the archive may be expanded. 266 | 267 | * Reference 268 | 269 | The reference behaves similar to the archive in that it contains data that is not actively in use. Tasks in the reference, 270 | however, may have *all of their metadata retained*, including time-sensitive metadata. 271 | 272 | Data and tasks may be pulled from the reference, but the syntax for doing so is not yet established. 273 | 274 | * Trigger List 275 | 276 | A trigger list is a list of general errands that you do frequently. You go through the list and think to yourself 277 | whether you have forgotten about anything from that given topic. Neorg will provide three different trigger lists 278 | by default: a personal trigger list, a student trigger list and a work trigger list. 279 | 280 | Below is an example snippet of a personal trigger list. If you ever remember anything about the presented topic capture it 281 | to the inbox as soon as possible: 282 | 283 | @code 284 | - Projects started, not completed 285 | - Projects that need to be started 286 | - Commitments/promises to others 287 | - Significant Other 288 | - Family 289 | - Friends 290 | - Classmates 291 | - Borrowed items 292 | - Projects: other organizations 293 | - Service 294 | - Civic 295 | - Volunteer 296 | - Communications to make/get 297 | - Family 298 | - Friends 299 | - Professional 300 | - Initiate or respond to: 301 | - Phone calls 302 | - Text messages 303 | - Voicemail 304 | - E-mail 305 | - Snail mail 306 | - Social Media 307 | - Upcoming events 308 | - Special occasions 309 | - Birthdays 310 | - Anniversaries 311 | - Weddings 312 | - Graduations 313 | - Holidays 314 | - Travel 315 | - Weekend trips 316 | - Vacations 317 | - Social events 318 | - Cultural events 319 | - Sporting events 320 | - Things to do 321 | - Places to go 322 | - People to meet/invite 323 | - Local attractions 324 | - Administration 325 | - Financial 326 | - Bills 327 | - Banks 328 | - Investments 329 | - Loans 330 | - Taxes 331 | @end 332 | 333 | *** User Experience 334 | 335 | Neorg will display trigger lists in a UI that will allow you to immediately add captures, closing the gap and making 336 | the mental model of a trigger list easier to deal with. 337 | 338 | * Review Process 339 | 340 | The review process happens usually at the end of every week. It involves taking a look at your projects, next actions and 341 | the amount of things you completed during the past week, and establishing a basic plan for next week. 342 | 343 | *** Automating the Review Process 344 | 345 | The user should be able to configure a static day of the week and time for a weekly review. Neorg will then 346 | automatically fill the calendar entry at that point every week with the appropriate due date. Neorg will also be able 347 | to calculate an estimated time (`~time`) of the whole review by doing some automatic, behind-the-scenes calculcations for 348 | each sector of the review process. This includes: 349 | - Counting the amount of projects that do not have a Next Action 350 | - Checking if the Next Actions ontology is empty, but the inbox is not (there are tasks left to process) 351 | - Counting the amount of overdue tasks 352 | - Counting the amount of someday/maybe tasks (which should also be reviewed) 353 | 354 | Based on usage data of the user (stored locally, of course) the average amount of time it takes to review a single task per sector 355 | can be adjusted to more closely match the actual speed of the user. 356 | 357 | The user may also opt not to set a static day for their review. If this is the case, Neorg may provide a yellow warning icon in the calendar 358 | view which, when clicked or opened with the appropriate keybind, would notify the user that they have not set a review date. 359 | This review date warning should also be configurable. 360 | 361 | *** The Review Date UI/UX 362 | 363 | It is important to operate within the limits of the TUI. The review process should be opened in a completely new tab, occupying the entire space 364 | and allowing the user to fully immerse themselves in the review process. 365 | 366 | Below is a prototype example of the UI. 367 | 368 | @code 369 | 370 | STEP 1/2 371 | 372 | 373 | PAST PRESENT FUTURE 374 | 375 | |-------------| |-------------| |-------------| 376 | | Tasks | | | | Next | 377 | | Completed | | OVERDUE | | Actions | 378 | | | | | | | 379 | | | -----> |-------------| -----> | | 380 | | | |-------------| | | 381 | | | | NO NEXT | | | 382 | | | | | | | 383 | | | | ACTIONS | | | 384 | |-------------| |-------------| |-------------| 385 | @end 386 | 387 | The review involves all things you have done, the things you need to do, and the actions you should take to make your future self 388 | more organized. 389 | 390 | **** Tasks Completed 391 | 392 | This display should show an overall percentage of what helped you achieve your goals. 393 | 394 | It should show all projects that were fully completed and what projects you made progress in the most. 395 | The last few lines should show the projects that haven't moved much. 396 | 397 | **** Overdue 398 | 399 | The overdue display should show all tasks that are currently overdue and must be handled in some way. 400 | It should be possible to interact with the tasks directly from the UI with a similar set of keybinds 401 | as the inbox processing phase (moving to archive, postponing etc.). 402 | 403 | Tasks with the highest urgency should be displayed first. 404 | 405 | **** NO NEXT ACTIONS 406 | 407 | This display should show all projects that do not have another Next Action defined for them, with 408 | the quick ability of adding a Next Action by showing the inbox in a popup. 409 | 410 | If there are no next actions but there are items in the inbox then there should also be a message 411 | telling the user they have no Next Actions defined. 412 | 413 | **** Next Actions 414 | 415 | The Next Actions display should show all of the next actions and allow you to verify if everything 416 | is still the way you wanted it. Editing, deleting and modifying the tasks should be as simple as it 417 | is in the other GTD UIs. 418 | 419 | --- 420 | 421 | Apart from the physical past, present and future realms you can also press `` to switch the view 422 | to the /hypothetical/ realm, aka the maybe/someday ontology. The view is also automatically switched after 423 | you have completed the first stage of your review. 424 | 425 | In this view you will see all hypothetical projects and ideas that you had, segmented by last interacted/modified 426 | and new ideas that you had in the last week, after which all other items from the ontology should follow. 427 | 428 | Here you may delete, move, build out ideas and anything else you would normally do with your m/s ontology, 429 | all with the same, familiar keybinds. 430 | 431 | *** Trigger List Prompt 432 | 433 | After a completed review, the user should also be prompted whether they would like to bring up their trigger list. 434 | If yes, ask for the profile of the trigger list and display it to the user! 435 | 436 | * The Calendar 437 | 438 | The calendar is the most sophisticated GTD display. 439 | 440 | An idea that the calendar /must/ understand is that *not all tasks are blocking*. 441 | Additionally, not all tasks require your attention throughout the entire span 442 | of doing the task. This is a serious shortcoming in most other time tracking applications, 443 | as they force you to allocate time for things that should be able to easily overlap with other 444 | tasks that you might want to do in the meantime. 445 | 446 | The calendar implementation is detached from GTD, and GTD merely interacts with the calendar 447 | to display information about upcoming, blocking/non-blocking, attentionful/attentionless tasks. 448 | 449 | * Graphs 450 | 451 | The easiest comparison to how a graph in GTD would look is similar to obsidian's graph view. 452 | Many nodes are interconnected to show relationships between data. 453 | 454 | Graphs will be rendered in a separate window from Neovim, as it is impossible to render good-looking 455 | graphs with mere unicode. Graphs also play well with mouse inputs for dragging around and clicking, therefore 456 | a GUI is almost critical for this task. 457 | 458 | * Motivating the User 459 | 460 | Neorg may opt to urge the user to get their tasks done every now and again 461 | (obviously under a configuration option). When the user has a few tasks to 462 | sift through, let them know they have not a lot left to go. If the user has a 463 | lot of tasks in their inbox, urge them by saying that sifting through just a 464 | few captures per day will quickly amount to serious progress. Do not let the 465 | user's tasks feel stale. 466 | 467 | The review process is usually seen as a chore, and therefore should be treated 468 | in a lighthearted and cheerful manner. Even a simple "Good Job!" would be enough, 469 | although we may want to have a streak system which counts how many times you've 470 | consecutively done a review. 471 | 472 | * Displays 473 | 474 | Tasks are sometimes difficult to visualize, especially once they grow greatly. Below are some concepts 475 | for making the visualization of tasks easier. 476 | 477 | *** Display All Tasks Related to a Context 478 | 479 | The following display could show all of the tasks that are related to a given context, a set of contexts (A or B) 480 | or a union of contexts (A and B) in the form of a graph of connections. 481 | 482 | *** Display Task Dependencies 483 | 484 | The following display would be shown in the form of a mindmap. Projects would branch out into tasks, and tasks that 485 | depend on other tasks would be marked with a one-way arrow. 486 | 487 | * General Considerations 488 | 489 | We should absolutely establish a single ruleset for how we set our keybinds. Currently they are a bit over the place. 490 | 491 | * Storage 492 | 493 | This section of the document covers how data is stored in the context of GTD. *All ontologies are stored as plain-text, 494 | readable Norg files*. Specifically, every ontology is an /unordered/ list of tasks if it's a general container (e.g. a project, an archive). 495 | If the data comes in the form of data that has to be processed in order (e.g. an inbox, a calendar, a trigger list) then the ontology 496 | is an /ordered list/ of tasks. 497 | 498 | There are some general rules that should be applied in all ontologies, and these are: 499 | 500 | ~ Use the default TODO syntax wherever possible. This includes done, undone, cancelled (archived) tasks alongside start dates, due dates and specific dates. 501 | ~ For more specific metadata, use `#` or `+` macro tags to signify more complex relationships (e.g. `#waiting.for `) 502 | 503 | A comprehensive list of macros will be released based on the demands of the implementation (no need to plan these out in the specification if most end up not 504 | being used). 505 | -------------------------------------------------------------------------------- /indentation-changes.norg: -------------------------------------------------------------------------------- 1 | @document.meta 2 | title: Indentation Ideas 3 | description: Concepts for a proper query syntax to~ 4 | make indentation using Treesitter less awful. 5 | authors: vhyrro 6 | categories: [ 7 | improvements 8 | treesitter 9 | ] 10 | created: 2022-01-01 11 | version: 0.0.9 12 | @end 13 | 14 | * Why the rewrite? 15 | Indentation is... hard, to say the least. 16 | There are several moving parts, and making everything work as 17 | intended can be really annoying. 18 | 19 | We don't want to simply just make a good solution for Neorg, ideally 20 | we'd like to make an implementation that will be easily translatable to 21 | `nvim-treesitter` itself - no more annoying indents 🤞. 22 | 23 | * Bugginess 24 | As a lot of people probably know treesitter indentation is really annoying 25 | at times. Because of the way TS works if you're editing at the beginning 26 | or end of a file you may find that `get_node_at_cursor` straight up returns 27 | `nil` and you're pretty much screwed. 28 | There are ways to mitigate this, and we will definitely try to create workarounds 29 | to alleviate bugs like this. 30 | 31 | * What's the plan? 32 | ** Plan A 33 | - Fix the `get_node_at_cursor`-at-end-of-file bug. 34 | 35 | ** Plan B 36 | To make indentation properly function we need a good way to define complex 37 | indents through treesitter queries. As of right now we are provided only 38 | 4 different captures: `@indent`, `@branch`, `@return` and `@ignore`. 39 | Let's just say... these aren't the best to work with lol. 40 | 41 | We can still keep those captures, that's fine by me, but we need more control. 42 | For example: 43 | 44 | @code query 45 | ( 46 | (my_node 47 | (nested_node) @nested-node 48 | ) @indent 49 | 50 | (#align-indent? @nested-node) 51 | ) 52 | @end 53 | 54 | I'd like to be able to align my indent to a certain node, that'd be great, wouldn't it? 55 | 56 | `#align-indent?` would also allow for static values like `0` or `10` instead of captures like `@nested-node`. 57 | Perhaps we could also create an `#align-indent-end?` attrib to start the indent from the end of the node? 58 | 59 | ** How Neorg and `nvim-treesitter` will tie together 60 | Ideally I'd love for us to implement our feature set in such a way that it'll easily be translatable to nvim-treesitter's repository. 61 | For this we need to make sure we're using `indents.scm` in our Neorg code and are using the inbuilt captures like `@indent` etc. 62 | 63 | When it comes to customizability nothing's stopping us from parsing a `config` table and building out a TS query file on the fly, then simply 64 | inputting it into `vim.treesitter`. How does that sound? 65 | 66 | * More advanced stuff for the future 67 | This isn't exactly related to Neorg (since Neorg doesn't have very complex syntax elements), but we definitely need to figure out a way to do relative indentation for 68 | programming languages for example. 69 | Take a look at this: 70 | 71 | @code lua 72 | if something then 73 | -- code should be indented here 74 | end 75 | @end 76 | 77 | That's perfectly fine, but then we have this: 78 | @code lua 79 | if 80 | something -- should be indented 81 | then 82 | -- code should be indented here 83 | end -- should be auto dedented 84 | @end 85 | 86 | I don't have exact ideas on how to tackle this yet but I believe just having more queries to account for more edge cases will work fine? 87 | If that's the case we'll need to have a system that'll detect which TS query to use (or we'll have to make our queries very strict). 88 | -------------------------------------------------------------------------------- /syntax/inline-link-targets/index.norg: -------------------------------------------------------------------------------- 1 | @document.meta 2 | title: Inline Link Targets 3 | description: Syntax proposal for in-line link targets. 4 | authors: mrossinek 5 | categories: syntax proposal 6 | created: 2021-12-20 7 | version: 0.0.9 8 | @end 9 | 10 | * Basic Idea 11 | Provide some syntax to specify targets which links can point to with some in-line markup, 12 | effectively allowing arbitrary (not entirely but for all practical purposes) placement within a file. 13 | 14 | ** Why? 15 | Allows linking to locations which may be difficult to get to if you do not want/cannot use a `| marker`. 16 | 17 | ** How? 18 | Place an ``. 19 | 20 | And link to it: `{> inline tag}`. 21 | 22 | $ Can we really use `>` as the link prefix? 23 | Yes, but this will prevent us from ever introducing links to quotes. 24 | I think this is fine though, since quotes don't have a title associated with them, via which one could link to them. 25 | Instead, one would probably use an in-line link target close to a certain quote. 26 | 27 | ** Example 28 | I am writing some prose. 29 | > This is a quote. 30 | This quote just now was very important. 31 | 32 | I can now continue writing. 33 | 34 | And later on link back to that really {> important quote}. 35 | 36 | ** Requirements 37 | - Treesitter 38 | -- another grammar group similar to anchor declarations 39 | -- another link location target 40 | 41 | - Neorg 42 | -- NFF spec update 43 | -- additions to the `hop` module 44 | 45 | - Other: 46 | -- neorg-telescope integration 47 | -- etc. 48 | -------------------------------------------------------------------------------- /syntax/multi-word-tag-parameters/index.norg: -------------------------------------------------------------------------------- 1 | @document.meta 2 | title: Multi-Word Tag Parameters 3 | description: 4 | authors: max 5 | categories: 6 | created: 2022-01-07 7 | version: 0.0.9 8 | @end 9 | 10 | * Basic Idea 11 | Enable the possibility of specifying tag parameters which consist of multiple words. 12 | 13 | ** Why? 14 | Currently, parameters are specified for example like so: 15 | 16 | = ToC Table of Contents 17 | 18 | While in this example, it makes sense that all three words are considered to be part of a single parameter (the /title/), this is not evident. 19 | Furthermore, other scenarios can be envisioned where more than one parameter are required and ambiguity will arise which words belong to which parameter. 20 | 21 | To alleviate that, we can introduce a _separator_ which can be manually inserted in order to disambiguate the parameter distinction. 22 | 23 | ** How? 24 | Looking at tables, the pipe character, `|`, seems like a good fit here, too: 25 | #choice multiple | Make any number of choices: 26 | (Example taken from {:../multiple-choice-questions/initial-ideas:}) 27 | 28 | ** Requirements 29 | - Treesiter 30 | -- special handling of `|` in tag/insertion parameters 31 | 32 | - Neorg 33 | -- nothing? 🤔 34 | -------------------------------------------------------------------------------- /syntax/multiple-choice-questions/final-ideas.norg: -------------------------------------------------------------------------------- 1 | @document.meta 2 | title: final-ideas 3 | description: 4 | authors: vhyrro 5 | categories: 6 | created: 2022-02-04 7 | version: 0.0.11 8 | @end 9 | 10 | * (somewhat) Final syntax proposal for MCQs 11 | ** Sometimes a carryover tag is all you need 12 | For our syntax we've decided that using Neorg itself is the perfect solution. 13 | Here's an example snippet: 14 | 15 | @code 16 | What is the best flavour of ice cream? 17 | |choice 18 | - |x| Chocolate 19 | - | | Mint 20 | - | | Vanilla 21 | @end 22 | 23 | The `choice` carryover tag by default specifies that only one choice may be made by the user. 24 | During render the user doesn't see `Chocolate` as "checked". That is simply an indicator of the correct 25 | choice. 26 | The `choice` tag takes in a single argument, and that argument can be an integer (`2`, `3`) or an expression 27 | (`<2`, `>4`). 28 | 29 | For more pleasant documents use whitespace: 30 | @code 31 | What is the best flavour of ice cream? 32 | 33 | |choice 34 | - |x| Chocolate 35 | - | | Mint 36 | - | | Vanilla 37 | @end 38 | --- 39 | 40 | An important thing to note is that `|choice` does *not* change how the text above the tag is rendered. 41 | Neorg strictly goes top to bottom. 42 | -------------------------------------------------------------------------------- /syntax/multiple-choice-questions/initial-ideas.norg: -------------------------------------------------------------------------------- 1 | @document.meta 2 | title: Multiple Choice Questions Syntax 3 | description: 4 | authors: vhyrro, max 5 | categories: 6 | created: 2021-12-20 7 | version: 0.0.9 8 | @end 9 | 10 | * Basic Idea 11 | A [proposal] was put forward to introduce a syntax for /questions and answers/. 12 | 13 | There are multiple aspects to this so I will try to separate them by logical use case. 14 | 15 | [proposal]{https://github.com/nvim-neorg/neorg/issues/232} 16 | 17 | ** Q & A 18 | A /Q & A/ or FAQ is generally a free-form, text-based collection of questions and answers. 19 | Also in a scenario of an interview (where questions and answers are gathered), this essentially does not change the syntax which could be used for an FAQ. 20 | 21 | For this free-form style, I believe the _definition_ syntax can be leveraged nicely. 22 | For example: 23 | 24 | $ What is Neorg? 25 | It is a tool designed to reimagine organization as you know it. 26 | 27 | of for more elaborate answers: 28 | 29 | $$ How do I get started with Neorg? 30 | You can install it with your favorite plugin manager and call the `setup()` function: 31 | 32 | @code lua 33 | require('neorg').setup { 34 | load = { 35 | ["core.defaults"] = {} 36 | } 37 | } 38 | @end 39 | $$ 40 | 41 | You can now easily link to these objects via {$ What is Neorg?} and {$ How do I get started with Neorg?} 42 | 43 | 44 | ** Muliple Choice Questions (MCQs) 45 | I would like to discuss MCQs in a more general manner. 46 | I.e. I would like to discuss them as /a construct to choose one or more options from a given selection/. 47 | 48 | In HTML, single-choice questions are usually rendered with so called /radio buttons/. 49 | Multiple radio button inputs can be tied into a mutually-exclusive group via their `name` attribute. 50 | When one such button gets selected, all other buttons within the same group will automatically get de-selected (/mutual exclusivity/). 51 | 52 | For multiple-choice scenarios, simple check-boxes are usually sufficient. 53 | I would like to pick up on one of our early ideas from the {* Original Discord Discussions} section, 54 | and suggest that we do _not_ differentiate these cases on the syntax of the elements to pick from, 55 | but instead modify their behavior via a _carryover tag_. 56 | 57 | There are various advantages to this: 58 | - changing from single- to multiple-choice is easy 59 | -- only requires changing tag parameters and not the syntax of all elements to choose from 60 | - we can choose a syntax _different_ from our TODO syntax 61 | -- in this way we do not need a special context in order to differentiate a TODO list from a multiple-choice question 62 | -- For example: is the following a TODO list or a multiple choice question? 63 | @code norg 64 | What am I? 65 | - [ ] a TODO list 66 | - [ ] a multiple-choice question 67 | @end 68 | To the TS parser this is ambiguous, which we generally try to avoid. 69 | -- One could argue that we may not have to care, but we should definitely not allow our more advanced TODO item states like `[?]`, etc. 70 | 71 | *** Syntax Proposal 72 | With all that said, I propose the following syntax: 73 | @code norg 74 | - ( ) Un-selected choice 75 | - (x) Selected choice 76 | @end 77 | The reasoning is very simple: 78 | - `- [ ]` is already taken by TODO items 79 | - `- { }` is ambiguous with links 80 | - `- ( )` feels natural and somewhat resembles a round radio button 81 | 82 | Since this is an entirely new syntax element, we can even embed this directly into a document: 83 | @code norg 84 | * I am a heading 85 | I am a paragraph. 86 | How do you like Neorg? 87 | - ( ) I am loving it! 88 | - ( ) I am still learning 89 | - ( ) Gotcha! Surely noone can answer negatively here... 90 | @end 91 | The TS parser can directly detect that this is an MCQ. 92 | 93 | *** Behavior Modification 94 | The behavior (or /kind/) of MCQ should be configurable via a _carryover tag_. 95 | Imo an MCQ should default to a single-choice question (since we are mimicing radio buttons here). 96 | For other cases, the `#choice` carryover tag can be used as suggested early on in {* Original Discord Discussions}. 97 | @code norg 98 | #choice 2 99 | - ( ) A 100 | - ( ) B 101 | - ( ) C 102 | @end 103 | Thus, the default would be `#choice 1`. 104 | Rather than introducing `single`, `multiple` and `limit`, we could go for a single argument style: `<2`, `2+`, `_` (for /any/), etc. 105 | But especially here I am open to better suggestions. 106 | 107 | The boundaries of the mutual exclusivity (configurable via the `#choice` tag) can be naturally set via the TS parser detecting the limits of the list of choices. 108 | For example, the following norg code: 109 | @code norg 110 | Question 1: 111 | - ( ) Option a 112 | - ( ) Option b 113 | 114 | Question 2: 115 | - ( ) Option a 116 | - ( ) Option b 117 | @end 118 | would be parsed similar to this: 119 | @code query 120 | (paragraph) 121 | (generic_list 122 | (choice) 123 | (choice) 124 | ) 125 | (paragraph) 126 | (generic_list 127 | (choice) 128 | (choice) 129 | ) 130 | @end 131 | Each `generic_list` poses natural bounds for the exclusivity between multiple choices. 132 | 133 | *** More Syntax (?) 134 | Given all of the above, I do not necessarily see the need for an additional syntax element, to frame MCQs with. 135 | Our original ideas contained an example similar to this: 136 | @code norg 137 | ? Select the coolest thing there is. 138 | # choice _ 139 | - ( ) Markdown 140 | - (x) Neorg 141 | - (x) org-mode 142 | @end 143 | I am not certain whether the `?`-detached modifier is really needed. 144 | Depending on the scenario this may just be a bold sentence, maybe a heading, or it could be integrated into the `#choice` tag (although this would give it somewhat dual purpose). 145 | I am open to suggestions whether or not such a syntax element is necessary. 146 | 147 | ** Forms 148 | We have now discussed the major aspects of this proposal. 149 | However, we now also have most things in place which would allow us to write proper *forms* in Neorg. 150 | We have syntax for questions (single or multiple choice), we can set up plain text fields (`@code` although `code` at this point would be mistitled), etc. 151 | 152 | Some aspects may still need some ironing out but overall I think most pieces are there... except one aspect: *analysis*. 153 | Analyzing forms means extracting the information that was filled in by the /user/. 154 | Since we have a TS parser for norg, this should be fairly easy! 155 | I think, we could add some tools built into Neorg to help with such a use case. 156 | For example, extract all user-supplied data and export it as structured data (`json` comes to mind). 157 | This would need some more aspects like names for all data fields but in general this should be fairly easy to do. 158 | 159 | In a similar fashion, quizzes (i.e. forms where a certain answer is correct/expected) could benefit from certain functionalities. 160 | For example, a teacher may choose to write a quiz in Neorg with pre-answered questions (i.e. writing a master solution) and would then wish to export the quiz norg file with all answers removed. 161 | This should also be fairly simple to do using our TS parser. 162 | 163 | This is more advanced stuff which will need to be built on top of the first aspects of this proposal but I wanted to have this written down somewhere. 164 | 165 | * Original Discord Discussions 166 | Just pasting some copy-pasta from discord with no real structure yet. 167 | 168 | @code norg 169 | ? Select the coolest thing there is. 170 | - [ ] Markdown 171 | - [x] Neorg 172 | - [x] org-mode 173 | @end 174 | 175 | @code norg 176 | #choice single | Make a choice now: 177 | - [ ] Invalid Choice 178 | - [x] Valid choice 179 | - [ ] Invalid choice 180 | @end 181 | 182 | @code norg 183 | #choice multiple | Make any amount of choices: 184 | - [ ] Invalid choice 185 | - [x] Valid choice 186 | - [x] Another valid choice 187 | @end 188 | 189 | @code norg 190 | #choice limit 2 | Make up to 2 choices: 191 | - [x] Valid 192 | - [x] Also valid 193 | - [ ] Invalid 194 | - [ ] Also invalid 195 | @end 196 | 197 | - A pipe | would essentially be a way to define parameters that have multiple words in them. 198 | -- See the separate proposal in {:../multi-word-tag-parameters/index:} 199 | 200 | Alternative: 201 | 202 | @code norg 203 | $ What OS should everyone be using? 204 | - ( ) Windows 205 | - (x) Linux 206 | - ( ) Mac OS 207 | @end 208 | -------------------------------------------------------------------------------- /syntax/zettelkasten/zettelkasten.norg: -------------------------------------------------------------------------------- 1 | @document.meta 2 | title: zettelkasten 3 | description: ideas for zettelkasten in neorg 4 | authors: neorg-dev 5 | categories: 6 | created: 2021-11-28 7 | version: 0.0.8 8 | @end 9 | 10 | * Goals 11 | ** Templates 12 | ** Links 13 | Links should use topic (first heading1?) as link text 14 | *** Follow 15 | - follow links (already implemented in neorg) 16 | -- splits 17 | -- directly 18 | *** Completion 19 | - get completion for links to other zettels 20 | -- by name (topic?) 21 | -- zettel number 22 | *** Backlinks 23 | **** Functionality 24 | There must a way of *automatic* backlinking: 25 | - In zettel $a$ you create a link to zettel $b$ > in zettel $b$ you can {**** Displaying}[display] the backlinks with commands or keybindings. 26 | - This should be automatically updated 27 | **** Displaying 28 | - opened in loclist or quickfixlist 29 | - opened in split neorg buffer (to follow them) 30 | -- preview 31 | --- open in float 32 | --- virtual text in split 33 | -- follow with (similar to toc) 34 | - open in telescope (follow on and preview) 35 | ** Tags 36 | use a syntax like `#tags neorg zettelkasten` 37 | *** Searching 38 | - allow searching by tags 39 | -- press a key on a tag or use command to {**** displaying}[display] other zettels with the same 40 | -- {# Telescope} 41 | *** Quick adding 42 | - provide a quick way to add existing tags to a Zettel 43 | -- search through existing tags with telescope 44 | -- completion 45 | ** Telescope 46 | Use telescope for searching Stuff 47 | - tags 48 | - note names 49 | 50 | ** Zettel 51 | - Document meta 52 | -- unique id 53 | - Heading 1: is used as title for zettel (link text) 54 | - tags (anywhere in the zettel?) 55 | - Actual text 56 | *** Example 57 | @code norg 58 | \@document.meta 59 | title: zettelkasten 60 | description: ideas for zettelkasten in neorg 61 | authors: max 62 | created: 2021-11-28 63 | version: 0.0.8 64 | id: 202111281750 65 | \@end 66 | #tags neorg zettelkasten 67 | * My Topic 68 | My nice content to the topic 69 | 70 | @end 71 | 72 | ** Zettelkasten 73 | - all the zettels, can be in folders -> doesn't matter how many subfolders 74 | - and index file with all zettels listed -> is this necessary? or do we want this anyway? 75 | 76 | * Implementation Ideas 77 | ** Linking 78 | - Database 79 | -- sqlite.nvim 80 | -- real database like org-roam v2 81 | --------------------------------------------------------------------------------