Giter Club home page Giter Club logo

waypoint's Introduction

Waypoint - Automatic Table of Contents Generator for Obsidian.md

Do you use folders to categorize your notes and wish that Obsidian would show certain folders in the graph view? Do you hate having to keep track of tags and links every time a file is created? Do you want to decide what folders should be categories without creating index files for every folder?

Waypoint is an Obsidian plugin that automatically generates tables of contents/MOCs within your folder notes. Once a waypoint is generated, it'll automatically link to every note within the folder and its subfolders. The Waypoint plugin will detect when you create/rename/move/delete a note and automatically stay up-to-date. No more dealing with loads of tags or manually updating your own content maps!

Preview Image

Features

  • Automatically generated tables of contents!
    • Waypoints are created whenever you type the magic word (default is %% Waypoint %%) within a folder note. A folder note is any note with the same name as its parent folder.
  • Instant updates whenever files/folders are created, renamed, moved, or deleted
    • File path changes trigger a scan for any waypoints that might be affected. If a waypoint is found, it is instantly updated in real-time.
  • Folders can now appear on the graph view
    • Just create a waypoint in a note with the same name as the folder and it'll automatically link to every file within, including files in subfolders!
    • Waypoints can be "nested" to avoid unnecessary links
      • Say your folders go from A -> B -> C. If you put a waypoint in the folder note of folder A, it'd include every file within folders A, B, and C. But if you create another waypoint in folder B, the first waypoint would only link to that folder note.
  • Fine-grained control over which folders are considered categories
    • Since you decide when and where a waypoint is generated in your folder tree, you can decide which folders could be considered "categories" and which are just for organizing.
    • Say you have a folder tree like Latin -> Chapter I -> Vocab -> .... "Latin" and "Chapter I" might be considered important enough to be called categories, but the "Vocab" folder within each chapter is just used to keep things organized. Other plugins might require that an index file is made in every folder, but Waypoint allows you to pick and choose what folder notes contain tables of contents. This means you can avoid creating a waypoint in each "Vocab" folder while still having the waypoints in each chapter folder like directly to each term. And because of how Waypoint prioritizes folder hierarchy, the waypoint in the folder note for "Latin" will only link to the chapter folder notes to avoid creating unnecessary links!
    • INTRODUCING: Landmarks!
      • Landmarks use the default magic word of %% Landmark %%
      • Landmarks are meant to be used between your waypoints to act as intermediary indexes. They can be placed in subfolder notes of waypoint tags to generate a "waypoint-like" tree without stopping a parent waypoint from including the child files/folders in your tree.
      • Expanding on the description for waypoints above, say you have a parent folder that holds languages such as Languages -> Latin -> Chapter I -> Vocab -> .... Similar to above, you want to have chapters listed for "Latin" and also have them show up on the "Language" folder note. This is achievable with Landmarks! By using %% Landmark %%, Waypoint will now generate an index in the current folder note listed as a landmark and will not stop the generation of the parent waypoint at that level, but keep going to list the chapters, as that is where the next waypoint is set.
  • Permanent and portable
    • Unlike other plugins, Waypoints are generated and saved as real markdown text within your folder notes. If you decide to switch to a different markdown editor that supports [[links]], all of your tables of contents will still be usable.
    • Note that the Waypoint plugin currently only works with Obsidian, so moving files around in another editor will cause your waypoints to be out-of-date.

How To Use

  • First, install the plugin. Waypoint is currently being reviewed for inclusion in the Community Plugins list. Once it is accepted, you'll be able to install it directly within Obsidian.
  • Generate a waypoint by editing a folder note (a note with the same name as its parent folder) and typing in the waypoint trigger text. By default, this is %% Waypoint %%. Make sure to include the double-percents on both sides!
    • This trigger flag can be changed in settings, but it will always require the double-percents in notes as that is how Obsidian knows it's a comment and not real text.
  • And that's it! Waypoints will be automatically updated whenever the files or folders within that folder are changed. Be sure not to remove the %% Begin Waypoint %% or %% End Waypoint %% flags as this is what the plugin uses to locate the table of contents. Any changes made to the text between these flags will get removed once the waypoint is updated.

Note that since waypoints can only be generated in folder notes, it is highly recommended that you install a plugin like Folder Note to ensure that folder notes don't get lost after folder renames and other actions that change the file tree. If a folder note containing a waypoint is renamed to something other than the folder's name, the waypoint will no longer be updated.

Current Limitations

  • Waypoints can only be created within a folder note
    • Because scanning for waypoints every time a file/folder is changed is an intensive process, only folder notes are checked to avoid scanning every file in the vault.
  • Waypoints cannot be created on the top level of your vault
    • Waypoints are meant to categorize notes that are similar to one another. Adding a waypoint to the root node would cause every note in your vault to be linked and defeat the point of using waypoints in the first place.
  • Waypoint appearance can't be customized (yet)
  • Only one waypoint can be created per folder note

If your workflow would be improved by the removal of one of these limitations, feel free to reach out to me with your use case and I'll see what I can do!

FAQ

Why should I use this instead of just using tags?

Tags are an easy way to sort and organize different notes by a type or category, but they have a few drawbacks that limit their usability. My personal reasons for not using tags extensively are that they need to be added or removed from a note manually and they cannot be nested in a meaningful way. Folders on the other hand are a clear and easy way to lump a bunch of notes into a specific category. And the ability to nest folders makes it a lot easier to document the relationship between individual categories. Using this plugin, you can easily link files in the same folder together without any manual bookkeeping (beyond creating the initial waypoint). I still find myself using tags for defining different types of notes since those are not likely to change even if I move them around.

How is this different from indexing plugins like Zoottelkeeper?

Zoottelkeeper and other related plugins are more complex and try to solve different problems. Zoottelkeeper automatically creates index files for every single folder in your repository (with customizable blacklists and whitelists). This means that each folder shows up on the graph view and only links to the index file in the folder immediately below the current one. This is great if you use folders sparingly and each folder has a significant and specific meaning, but if you use folders as your main method of organization then your graph will quickly become messy.

Waypoint was created to give users fine-grained control over what folders are significant enough to be considered a "category" of notes. It allows you to create tables of content that link not only to the files in the same folder but to files in subfolders as well. And if you decide that certain subfolders are worthy of a subcategory of their own, creating a waypoint there will automatically prune the parent waypoint and update it to link only to that folder's folder note. If you prefer to have your waypoints only link to the nearest folder note (whether or not they contain a waypoint), you can enable that functionality within the settings.

Get In Touch

Got any questions, comments, or concerns? Feel free to raise an issue through GitHub or get in touch with me @IdreesInc. If you want to see some of my other projects, check out my website idreesinc.com.

waypoint's People

Contributors

coanghel avatar donthorp avatar gyukai avatar havinleung avatar idreesinc avatar ironman820 avatar javeoff avatar tbdcit avatar vburzynski avatar zhelding avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

waypoint's Issues

Obsidian mobile freezes when adding or updating a waypoint

On iOS/iPadOS, Obsidian freezes and restarts when I create a new file. The new file is successfully created but apparently not indexed because it doesn't appear in the Quick Switcher recent list.

Disabling Waypoint eliminates the problem.

EDIT: I recently turned Waypoint back on so I could add a file list to a note, and found I couldn’t do it. Each time I added the Waypoint comment, Obsidian froze. Reinstalling the plugin didn’t help (I disabled it and restarted Obsidian before reinstalling).

Create unit tests

Waypoint needs unit tests badly, mainly with the getFileTreeRepresentation function.

Waypoint don't detect create a folder note with 'Key for New Note' in Folder Note Extension

Example a folder note index:

- [[Main Folder]]
  - [[Simple Note]] 

I create a folder with a name, example "Sub Folder". Main Folder note update normally.

- [[Main Folder]]
  - [[Simple Note]]
  - Sub Folder

I create Sub Folder's folder note with click the folder by key in the Folder Note extension.
image

But backlinks don't update in Main Folder's folder note.

- [[Main Folder]]
  - [[Simple Note]]
  - Sub Folder

Sorting Backlinks Options

Waypoints sort backlinks by document names. It would be great to have the option to sort the backlinks by creation date, modified date, or by various properties or manually.

Feature Request: Option to index other file extension types

I would like to use waypoint in place of zootelkeeper, but I depend on Zootelkeepers' indexing of .docx, pdf, and other file formats. Could this be enabled in waypoint? Some sort of way to indicate the filetype beyond an extension (i.e. by setting emoji or icons) would be excellent as well, but more minor :)

Add Ability to Hide Waypoint Note

Hiya there,

I'd like to hide the note holding the Waypoint, from the list of Waypoints.

E.g. the page contains itself, as a waypoint, and I'd like to hide that.

TOC

Can you add option to show automatically TOC of the file? Not just folder structure. Expanding the by this feature the plugin can really become the waypoint! Thanks for plugin

Create Link with definitive path instead of file name

Waypoint links an incorrect file that are located in root folder when I have files have same titles.
For example, in Folder note "Folder-A" Waypoint would link "root/File-1" instead of "root/Folder-A/File-1".

Zoottelkeeper use pipe to solve this problem, discussion about the issue here

Link would be like this in this way
[[Folder-A/File-1 | File-1]]

I really love the way this plugin works, so I hope that Waypoint have 'definitive path link'.
Sorry if there is any intention not to use definitive link but file name.
Thanks for your time!

Feature request: add "Insert Waypoint flag" command

Thank you for making this great extension!

I think it would make sense to have a command that simply inserts %% Waypoint %% at the current cursor position. I keep forgetting the exact syntax and have to look it up in the plugin's settings just to type it out manually.

Correct README - Nested Tags

I had this plugin in my backlog of plugins to try. I was wondering, why is this better than using tags?

Well, the README addresses that. But seems unaware that nested tags do exist (#this/is/nested). Not to mention, 'manually' adding a tag is similar to 'manually' moving notes into folders or searching+selecting folders to create notes in.

All my Waypoints stop updating and can't create new ones

Hi, recently I notice that my waypoint where not update. I when I delete one and tried to recreate it I receive this message %% Error: Cannot create a waypoint in a note that's not the folder note. For more information, check the instructions [here](https://github.com/IdreesInc/Waypoint) %% although I used to have one in that folder note. Also, I couldn't create new ones, I always receive the same message, no matter what folder I try.

FR: option to list notes with first alias or heading instead of title

It would be nice to have an option with a dropdown menu allowing to choose how to have the notes visualized in the waypoint lists, with three options: title, first alias, fist heading.
This may be useful in many use cases, but very useful oor those who name their notes with a numeric and/or hierarchical notation, and then change the displayed name using plugins (such as Froint Matter Title).

So for example a note like this:

TitleOfTheNote

Aliases:

  • Alias1
  • Alias2

Heading1

Test

Heading2

Other Text

could be shown in the Waypoint list, according to the choice in the Options, as:

[[TitleOfTheNote]] or [[TitleOfTheNote|Alias1]] or [[TitleOfTheNote|Heading1]]

It doesn't update the link after adding a folder note

When we add a descendant directory, there is a non-active bold link to it that appears. That's right, because the folder is empty.
Then, if we create the new folder note inside this folder, the link to it is still inactive.

If a backquote is in file name the index is corrupted

I suspect this is true for other special characters, but I had a file that somehow has a backquote {`) in it. Waypoint just used the filename and hence all the names after that in the folderindex were not clickable. Perhaps you should strip out (regex you create and allow user to voerride), or in the index you correct this by using the URL type escape (%xx) or something

More options for WikiLinks

I was looking for an automated MOC for quite some time and your plugin is absolutely amazing. To make it even better, more options for WikiLinks would be nice.

WikiLinks can use 3 types of links: shortest, relative or absolute path. Currently it's always shortest path. It would be great if you could add the ability to change it to relative or absolute path.

And also it would be awesome to have an option to insert the first alias of a note as alias of the WikiLink, like so: [[path/to/note|Note Alias]]
Without the alias, the link shows the complete path, which is pretty redundant.

I don't know if any of this is rather easy or highly complicated, but it would be great to have that functionality. Thanks a lot in advance.

Root folder waypoints

Great plugin! For those of us who use Obsidian Publish, it would be great if the plugin allowed for the creation of a waypoint at the root folder of the vault, because that could then be used as a ToC/full index for the landing page of the published site.

Feature Request: links to folder notes on their names

Now it's like this:

Projects

  • Celeste
    • [[Celeste Video Script]]
    • [[Celeste]]
  • [[Projects]]

According to me, it would be less messy and more efficient like this:

[[Projects]]

  • [[Celeste]]
    • [[Celeste Video Script]]

Great plugin, BTW!

*.md.tmp files seem to cause sync issues with Syncthing

Thanks for your helpful plugin.

I have an issue with syncing. It produces sync-conflicts with Syncthing (latest).

image

image

I guess, that a tmp file is the cause. So I added

'(?d)(?i)*.md.tmp`

to exclude these files from syncing.

Is this all I can do to solve the issue? (If so, could you please give a hint in the documentation?)

Links to empty notes created

When I add a Waypoint to a Folder Note it lists all the notes, but some of the links are not to the actual note, but to notes that do not yet exist. Why is that? The notes exist. Why isn't Waypoint linking to them?

Exclude folders/files by name or regex

I use the folder "Archive" to put all archived contents, and I don't want any of the waypoints to include this directory if it is present. It'd be cool to exclude paths by regex or strings.

Thanks for the cool plugin!

Support spaces instead of tabs

I lint my notes for consistency and use spaces, not tabs for indentation. I'd like this plugin to be consistent with this. Maybe it could read what the core editor settings (Use tabs, Tab size) are set to and follow that, or have an option where I can adjust it manually.

Feature Request: Support customized prefix of node

Thanks for your plugin! It's fantanstic !

I wonder whether we can customize the prefix of the created list node like below :

%% Begin Waypoint %%

  • [[folder_name]]
    • Children:: [[file1]]
    • Children:: [[file2]]
    • Children:: [[file3]]

%% End Waypoint %%

So that Waypoint can work with other excellent graph view plugins such as excalibrain perfectly! That make sense a lot !

Waypoint plugin fails to load

Hello! I just installed this plugin, but it fails to load when I try to enable it. I get the following error in the console:

app.js:1 Plugin failure: waypoint SyntaxError: Unexpected token '<'
    at eval (<anonymous>)
    at app.js:1:1444405
    at e.<anonymous> (app.js:1:1444467)
    at app.js:1:127354
    at Object.next (app.js:1:127459)
    at s (app.js:1:126198)

Option to Disable "Nesting"

I started using Waypoint as a way to group different subjects together via folders etc. I was able to connect the primary subject to every note within it. Then connect a sub-subject by adding a waypoint into a sub-folder, etc. This made it so in graph view, I could see all the notes connected to one subject, then onto all the same notes that were also included in a sub-subject and which notes were not. And vise versa, I could hover over one note, and see all the subjects connected to it.
However, this made it so that the waypoint of a higher folder, did not update new notes in lower folders, due to the "nesting". And if I deleted a higher folder note and refreshed it, it would then only show the folders, not the notes inside each folder. This then defeated the point of what I wanted.
Is it possible to make the "nesting" part optional so that I can have those "unnecessary" which are quite necessary for the type of logic notes I'm doing?
Thank you for your time!

Feature request: "refresh all waypoints"

I'd like to see a command added that would go through my vault and refresh all Waypoints. This is sometimes necessary and I don't know why, but fairly often I come across a folder note that is improperly indexed. For example, perhaps I modified the files outside of Obsidian or who knows what the reason is. But I'd like to be able to say "rescan my vault and update all Waypoints."
Thanks!

ability to ignore some folders

I think there should be a setting option where we can ignore some folders. For example, we don't want to include the attachments folder in waypoints.

Folders sorted to the top

Folders should have a higher priority and should be listed ahead of the file list rather than alphabetically

support the index file method of Folder Note

Great idea for an Obsidian plugin. Love the control it affords when it comes to when to add the triggering tag. However, I would like to use the index file method of Folder Note, where the folder note does not have the same name as the folder, but instead has a common name across all folder (e.g. about.md). I would be fantastic if Waypoint could support this functionality.

Prevent folder note from showing itself

Hi and thanks for the useful plugin.
Is there a way to prevent the folder note from referencing itself? For example in the list below, I do not need "Issues" to appear in the list of issues.

image

Different behavior for subfolders in inside and outside notes

After the inside and outside note were added (which I really hoped for, moving a big project dictionary to Obsidian, and happy that Waypoint exists and makes perfect alphabetization), there are some inconsistencies in Waypoint shows subfolders.
In an folder note that is inside the folder, the subfolders are shown as follows:

- [[ἀλλοίωσις]]
	- **ἄλλος**
	- [[ἄλλο ἄλλου]]
	- [[ἄλλος καὶ ἄλλος]]
	- [[πρὸς ἄλλο καὶ παρ' ἄλλου]]
- [[ἄλλος]]
- [[ἄλογος]]

The folder note is duplicated, showing once as a folder which is not a link, and below as a link to the note

In an outside note, they show as follows, without nested notes:

- [[ἀλλοίωσις]]
- **[[ἄλλος]]**
- [[ἄλογος]]

What I hope for, would look like that:

- [[ἀλλοίωσις]]
	- **[[ἄλλος]]**
	- [[ἄλλο ἄλλου]]
	- [[ἄλλος καὶ ἄλλος]]
	- [[πρὸς ἄλλο καὶ παρ' ἄλλου]]
- [[ἄλογος]]

FR: Add a ! in front of note links

HI there, great plugin. I have an idea for a feature which would add some extra power to your plugin. I could use this feature quite a bit.

I propose that you add a setting to your plugin, which adds a ! symbol to the front of the [[Note]] link that it currently does. By adding the !, it turns it into a dynamic embed of that file.

This feature would allow the user to generate a glossary of the current directory, peering into the contents of each file. This could be very useful for directories with smaller/quick notes (i.e. a slipbox).

There is already a plugin that technically does this (called Auto Glossary) however it does not automatically generate the content live, so the user must regenerate the page manually. By adding this feature to your plugin, and it being dynamically generated and updated, it solves all of my needs.

Ideally this would be triggered as a command, although I see your current methodology is to use the %% commenting, so at the least this feature could be added as a setting. If you do transition to using commands, this would be good for that.

Thanks

Prevent linking to the self referencing Waypoint file.

When creating a Waypoint file, the list references itself. Is there a way to prevent this? For example, assuming I have the following:

Spice (folder)

  • Jessica (file)
  • Leto (file)
  • Paul (file)
  • Spice (file) <--- Waypoint

The Waypoint file, "Spice," would list the following:

  • Jessica
  • Leto
  • Paul
  • Spice

You don't need the file to link to itself.

Feature Request: more flexible choice of waypoints

"Say your folders go from A -> B -> C. If you put a waypoint in the folder note of folder A, it'd include every file within folders A, B, and C. But if you create another waypoint in folder B, the first waypoint would only link to that folder note."

This is a great idea, but it's not so flexible.
As it is now, if I want to have a index on B, but still show all content of B in the index on A, I can't.
So, what about having two different flags, one that only generate the index (for example %% Index %%), and one that generates the index and actually marks a waypoint (for example %% Waypoint %%)?
In this way, I could put %% Waypoint %% in A and %% Index %% in B, and get what I wanted: index both in A and in B, and the index in A showing also all the content of B :)

FR: Possibility of placing Waypoint inside Callouts?

Not sure how the automatic checking of updates works with Waypoint, or if it's possible to make this a future addition. But it would be nice to be able to put Waypoints inside a Callout to make it a collapsible part of the folder note and it still detect changes made in the folder structure. Right now it can be moved inside of a callout to keep the static index but can't update for any changes made.

Duplicate note names generate wrong links

Consider the following structure:

notes
+- A
|  `- Test
+- B
|  `- Test
`- C
   `- Test

Assuming the directories A, B, C have folder notes. Then adding %% Waypoint %% to each folder note, will generate [[Test]] in all of them, instead of [[A/Test]], [[B/Test]], and [[C/Test]].

My current workaround is to disable "Use WikiLinks" in Waypoint's settings.

support writing markdown links

One of the best aspects of Waypoint is it focus on maintaining portability by writing links to the folder note markdown file. A big step in that direction would be to have the option to write markdown links instead of wikilinks. Ideally, the plugin would use the setting described under Obsidian's "Files & Links" settings page (specifically, "New link format", "Use [[Wikilinks]]" and "Detect all file extensions" and adjust its behavior accordingly. That would afford maximum portability and allow the behavior of Waypoint to stay consistent with the rest of a user's vault. Thanks so much for writing this.

Include "excerpts" of notes in waypoints.

I'm fairly new to using the Waypoint plugin, and already finding I'd love to include a short except from a note into the generated waypoint. Something like:

%% Begin Waypoint %%
- [[Dagger]] - Programmable CI/CD Pipelines using _real_ programming languages.
%% End Waypoint %%

and in the front matter of the target page, something like:

summary: Programmable CI/CD Pipelines using _real_ programming languages.

or

summary-source: first-paragraph

Has anyone suggested/thought about something similar before?

BUG: Unable to update the waypoint of the folder note of two folders at the same time

If I add a folder note in folder A (with waypoint added) and there is a folder B in folder A, when folder B creates a folder note with waypoint added, the waypoint in the folder note in folder A will not be updated (although the setting "Stop Scan at Folder Notes" has been turned off).
image

And when a note is added to folder B, the waypoint in the folder note in folder B will be updated, but the waypoint in the folder note in folder A will not be updated.
image

This bug only appears when a waypoint is added to the folder note in folder B. If the folder note in folder B is only a blank note, there is no such bug
image

Sorting options

Thanks for this great plugin!
It would be very useful to have an option to change the way notes are listed, e.g. to sort them by creation date.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.