diff --git a/README.md b/README.md index d12fb69..c70b2c4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ > This is a simple version of README which highlights the **basic scenario and most commonly used feature** > -> The [long and much more detailed advanced-README.md is here](./advanced-README.md) +> The [long and much more detailed advanced-README.md is here](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/advanced-README.md) --- ## Freely arrange notes and folders in File Explorer (https://obsidian.md plugin) @@ -39,8 +39,8 @@ sorting-spec: | --- ``` -Click the ribbon button (![Inactive](./docs/icons/icon-inactive.png) or ![Static icon](./docs/icons/icon-mobile-initial.png) on phone) to tell the plugin to read the sorting specification and apply it. -The sorting should be applied to the folder. On desktops and tablets the ribbon icon should turn (![Active](./docs/icons/icon-active.png)) +Click the ribbon button (![Inactive](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-inactive.png) or ![Static icon](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-mobile-initial.png) on phone) to tell the plugin to read the sorting specification and apply it. +The sorting should be applied to the folder. On desktops and tablets the ribbon icon should turn (![Active](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-active.png)) !!! **Done!** !!! @@ -48,30 +48,30 @@ You should see the files and sub-folders in your folder sorted in reverse alphab An illustrative image which shows the reverse alphabetical order applied to the root folder of some vault: -![Basic example](./docs/svg/simplest-example-3.svg) +![Basic example](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/simplest-example-3.svg) --- ### Remarks > Remarks: -> - your new `sortspec` note should [look like this](./docs/examples/basic/sortspec.md?plain=1) except for the syntax highlighting, which could differ +> - your new `sortspec` note should [look like this](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/examples/basic/sortspec.md?plain=1) except for the syntax highlighting, which could differ > - you will notice that the folders and files are treated equally and thus intermixed > - the behavior depends on what files and subfolders you have in your folder > - changing the sorting order via the standard Obsidian UI button won't affect your folder, unless... -> - ...unless you deactivate the custom sorting via clicking the ribbon button to make it (![Inactive](./docs/icons/icon-inactive.png)) +> - ...unless you deactivate the custom sorting via clicking the ribbon button to make it ![Inactive](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-inactive.png) > - for clarity: the underlying file of the note `sortspec` is obviously `sortspec.md` -> - in case of troubles refer to the [TL;DR section of advanced README.md](./advanced-README.md#tldr-usage) +> - in case of troubles refer to the [TL;DR section of advanced README.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/advanced-README.md#tldr-usage) > - feel free to experiment! The plugin works in a non-destructive fashion, and it doesn't modify the content of your vault. > It only changes the order in which the files and folders are displayed in File Explorer > - indentation matters in YAML -> the two leading spaces in ` order-desc: a-z` are intentional and required -> - this common example only touches the surface of the rich capabilities of this custom sorting plugin. For more details go to [advanced version of README.md](./advanced-README.md) +> - this common example only touches the surface of the rich capabilities of this custom sorting plugin. For more details go to [advanced version of README.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/advanced-README.md) --- ## Basic scenario 2: explicitly list folders and files in the order which you want This comes from the suggestion by [TheOneLight](https://github.com/TheOneLight) in [this discussion](https://github.com/SebastianMC/obsidian-custom-sort/discussions/95#discussioncomment-7048584) -Take the instructions from the **[Basic scenario 1](https://github.com/SebastianMC/obsidian-custom-sort#basic-scenario-set-the-custom-sorting-order-for-a-specific-folder)** above and replace the YAML content with: +Take the instructions from the **[Basic scenario 1](#basic-scenario-set-the-custom-sorting-order-for-a-specific-folder)** above and replace the YAML content with: ```yaml --- @@ -137,7 +137,7 @@ The list of basic automatic sorting orders includes: ## Manual sorting The **manual ordering of notes and folders** is also done via the sorting configuration. -Refer to the [TL;DR section of advanced README.md](./advanced-README.md#tldr-usage) for examples and instructions +Refer to the [TL;DR section of advanced README.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/advanced-README.md#tldr-usage) for examples and instructions ## Ribbon icon @@ -145,26 +145,26 @@ Click the ribbon icon to toggle the plugin between enabled and suspended states. States of the ribbon icon on large-screen devices (desktops, laptops and tablets like iPad): -- ![Inactive](./docs/icons/icon-inactive.png) Plugin suspended. Custom sorting NOT applied. -- ![Active](./docs/icons/icon-active.png) Plugin active, custom sorting applied. -- ![Error](./docs/icons/icon-error.png) Syntax error in custom sorting configuration. -- ![General Error](./docs/icons/icon-general-error.png) Plugin suspended. General error. -- ![Sorting not applied](./docs/icons/icon-not-applied.png) Plugin enabled, but the custom sorting was not applied. -- ![Static icon](./docs/icons/icon-mobile-initial.png) (Only on large-screen mobile devices like iPad). +- ![Inactive](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-inactive.png) Plugin suspended. Custom sorting NOT applied. +- ![Active](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-active.png) Plugin active, custom sorting applied. +- ![Error](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-error.png) Syntax error in custom sorting configuration. +- ![General Error](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-general-error.png) Plugin suspended. General error. +- ![Sorting not applied](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-not-applied.png) Plugin enabled, but the custom sorting was not applied. +- ![Static icon](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-mobile-initial.png) (Only on large-screen mobile devices like iPad). Plugin enabled. but the custom sorting was not applied. On small-screen mobile devices (phones) the icon is static: -- ![Static icon](./docs/icons/icon-mobile-initial.png) The icon acts as a button to toggle between enabled and disabled. Its appearance doesn't change +- ![Static icon](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-mobile-initial.png) The icon acts as a button to toggle between enabled and disabled. Its appearance doesn't change -For more details on the icon states refer to [Ribbon icon section of the advanced-README.md](./advanced-README.md#ribbon-icon) +For more details on the icon states refer to [Ribbon icon section of the advanced-README.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/advanced-README.md#ribbon-icon) ## Small screen mobile devices remarks - you might need to activate the custom sorting on your mobile separately, even if on a shared vault the custom sorting was activated on desktop - the Obsidian command palette being easily available (swipe down gesture on small-screen mobiles) allows for quick steering of the plugin via commands: sort-on and sort-off. This could be easier than navigating to and expanding the ribbon -- the ribbon icon is static (![Static icon](./docs/icons/icon-mobile-initial.png)) and doesn't reflect the state of custom sorting. +- the ribbon icon is static (![Static icon](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-mobile-initial.png)) and doesn't reflect the state of custom sorting. You can enable the _plugin state changes_ notifications in settings, for the mobile devices only ## Installing the plugin @@ -175,7 +175,7 @@ The plugin could and should be installed from the official Obsidian Community Pl or directly in the Obsidian app itself. Search the plugin by its name 'CUSTOM FILE EXPLORER SORTING' -> For other installation methods refer to [Installing the plugin section of advanced-README.md](./advanced-README.md#installing-the-plugin) +> For other installation methods refer to [Installing the plugin section of advanced-README.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/advanced-README.md#installing-the-plugin) ## Credits @@ -186,7 +186,7 @@ in [obsidian-bartender](https://github.com/nothingislost/obsidian-bartender) Do you want to have a nice-looking horizontal separators in File Explorer like this? -![separators](./docs/img/separators-by-replete.png) +![separators](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/img/separators-by-replete.png) If so, head on to [Instruction and more context](https://github.com/SebastianMC/obsidian-custom-sort/discussions/57#discussioncomment-4983763) by [@replete](https://github.com/replete)\ diff --git a/advanced-README.md b/docs/advanced-README.md similarity index 85% rename from advanced-README.md rename to docs/advanced-README.md index 3e6d472..ec48c88 100644 --- a/advanced-README.md +++ b/docs/advanced-README.md @@ -1,6 +1,6 @@ # Advanced version of README.md for advanced users -The [simplified README.md is here](./README.md) +The [simplified README.md is here](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/README.md) ## Freely arrange notes and folders in File Explorer (https://obsidian.md plugin) @@ -52,11 +52,11 @@ Take full control of the order of your notes and folders: ## TL;DR Usage -For full version of the manual go to [manual](./docs/manual.md) and [syntax-reference](./docs/syntax-reference.md) +For full version of the manual go to [manual](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/manual.md) and [syntax-reference](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/syntax-reference.md) > **Quickstart** > -> 1. Download the **RAW CONTENT** of [sortspec.md](./docs/examples/quickstart/sortspec.md?plain=1) file and put it in any folder of your vault, +> 1. Download the **RAW CONTENT** of [sortspec.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/examples/quickstart/sortspec.md?plain=1) file and put it in any folder of your vault, can be the root folder. Ensure the exact file name is `sortspec.md`. That file contains a basic custom sorting specification under the `sorting-spec:` name in the YAML frontmatter. > > IMPORTANT: follow the above link to 'sortspec.md' and download (or copy & paste) the __RAW__ content of that file, not the HTML displayed by github. > > Afterwards double check that the content of `sortspec.md` file is not an HTML and: @@ -65,19 +65,19 @@ can be the root folder. Ensure the exact file name is `sortspec.md`. That file c > > - indentation is correct (consult images below). In YAML the indentation matters. > > > > In other words, ensure, that the final `sortspec.md` file in your vault (which is the `sortspec` Obsidian note) looks exactly like below: -> > ![sortspec.md](./docs/img/sortspec-md-bright.jpg) +> > ![sortspec.md](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs//img/sortspec-md-bright.jpg) > > > > or if you are a fan of dark mode (line numbers shown for clarity only, they aren't part of the file content): > > -> > ![sortspec.md](./docs/img/sortspec-md-dark.jpg) +> > ![sortspec.md](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs//img/sortspec-md-dark.jpg) > 2. Enable the plugin in obsidian. > -> 3. Click the ribbon button (![Inactive](./docs/icons/icon-inactive.png) or ![Mobile](./docs/icons/icon-mobile-initial.png) on phone) to tell the plugin to read the sorting +> 3. Click the ribbon button (![Inactive](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-inactive.png) or ![Mobile](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-mobile-initial.png) on phone) to tell the plugin to read the sorting specification from `sortspec` note (the `sortspec.md` file which you downloaded a second ago). > - The observable effect should be reordering of items in root vault folder to reverse alphabetical with folders and files treated equally. And on computers and tablets be the change of appearance of the ribbon button to -![Active](./docs/icons/icon-active.png) (on desktop and tablet only) and -> - The notification balloon should confirm success: ![Success](./docs/icons/parsing-succeeded.png) +![Active](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-active.png) (on desktop and tablet only) and +> - The notification balloon should confirm success: ![Success](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/parsing-succeeded.png) > 4. Click the ribbon button again to suspend the plugin. The ribbon button should toggle its appearance again and the order of files and folders in the root folder of your vault should get back to the order selected in Obsidian UI @@ -87,8 +87,8 @@ change. This will suspend and re-enable the custom sorting, plus parse and apply > - If you don't have any subfolder in the root folder, create one to observe the plugin at work. > -> NOTE: the appearances of ribbon button also includes ![Not applied](./docs/icons/icon-not-applied.png) -and ![Error](./docs/icons/icon-error.png). For the meaning of them please refer to [ribbon icon](#ribbon_icon) section below +> NOTE: the appearances of ribbon button also includes ![Not applied](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-not-applied.png) +and ![Error](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-error.png). For the meaning of them please refer to [ribbon icon](#ribbon_icon) section below Below go examples of (some of) the key features, ready to copy & paste to your vault. @@ -123,11 +123,11 @@ sorting-spec: | < a-z --- ``` -(View or download the raw content of [sortspec.md](./docs/examples/1/sortspec.md?plain=1) file of this example) +(View or download the raw content of [sortspec.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/examples/1/sortspec.md?plain=1) file of this example) which can result in: -![Simplest example](./docs/svg/simplest-example.svg) +![Simplest example](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/simplest-example.svg) ### Simple case 2: impose manual order of some items in root folder @@ -149,7 +149,7 @@ sorting-spec: | produces: -![Simplest example](./docs/svg/simplest-example-2.svg) +![Simplest example](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/simplest-example-2.svg) ### Example 3: In root folder, let files go first and folders get pushed to the bottom @@ -177,7 +177,7 @@ sorting-spec: | will order items as: -![Files go first example](./docs/svg/files-go-first.svg) +![Files go first example](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/files-go-first.svg) ### Example 4: In root folder, pin a focus note, then Inbox folder, and push archive to the bottom @@ -205,7 +205,7 @@ sorting-spec: | and the result will be: -![Result of the example](./docs/svg/pin-focus-note.svg) +![Result of the example](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/pin-focus-note.svg) > Remarks for the `target-folder:` > @@ -233,11 +233,11 @@ sorting-spec: | --- ``` -(View or download the raw content of [sortspec.md](./docs/examples/5/sortspec.md?plain=1) file of this example) +(View or download the raw content of [sortspec.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/examples/5/sortspec.md?plain=1) file of this example) which will have the effect of: -![Result of the example](./docs/svg/p_a_r_a.svg) +![Result of the example](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/p_a_r_a.svg) ### Example 6: P.A.R.A. example with smart syntax @@ -257,7 +257,7 @@ sorting-spec: | It will give exactly the same order as in previous example: -![Result of the example](./docs/svg/p_a_r_a.svg) +![Result of the example](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/p_a_r_a.svg) ``` REMARK: the wildcard expression '...' can be used only once per line @@ -303,7 +303,7 @@ sorting-spec: | will have the effect of: -![Result of the example](./docs/svg/multi-folder.svg) +![Result of the example](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/multi-folder.svg) ### Example 9: Sort by numerical suffix @@ -330,7 +330,7 @@ alphabetical ascending. The effect is: -![Order by numerical suffix](./docs/svg/by-suffix.svg) +![Order by numerical suffix](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/by-suffix.svg) ### Example 10: Sample book structure with Roman numbered chapters @@ -352,7 +352,7 @@ sorting-spec: | it gives: -![Book - Roman chapters](./docs/svg/roman-chapters.svg) +![Book - Roman chapters](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/roman-chapters.svg) ### Example 11: Sample book structure with compound Roman number suffixes @@ -372,7 +372,7 @@ sorting-spec: | the result is: -![Book - Roman compound suffixes](./docs/svg/roman-suffix.svg) +![Book - Roman compound suffixes](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/svg/roman-suffix.svg) ### Example 12: Apply same sorting to all folders in the vault @@ -572,31 +572,31 @@ Click the ribbon icon to toggle the plugin between enabled and suspended states. States of the ribbon icon on large-screen devices (desktops, laptops and tablets like iPad): -- ![Inactive](./docs/icons/icon-inactive.png) Plugin suspended. Custom sorting NOT applied. +- ![Inactive](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-inactive.png) Plugin suspended. Custom sorting NOT applied. - Click to enable and apply custom sorting. - Note: parsing of the custom sorting specification happens after clicking the icon. If the specification contains errors, they will show up in the notice baloon and also in developer console. -- ![Active](./docs/icons/icon-active.png) Plugin active, custom sorting applied. +- ![Active](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-active.png) Plugin active, custom sorting applied. - Click to suspend and return to the standard Obsidian sorting in File Explorer. -- ![Error](./docs/icons/icon-error.png) Syntax error in custom sorting configuration. +- ![Error](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-error.png) Syntax error in custom sorting configuration. - Fix the problem in specification and click the ribbon icon to re-enable custom sorting. - If syntax error is not fixed, the notice baloon with show error details. Syntax error details are also visible in the developer console -- ![General Error](./docs/icons/icon-general-error.png) Plugin suspended. General error. +- ![General Error](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-general-error.png) Plugin suspended. General error. - File Explorer not available or other type of general error - File Explorer is a core Obsidian plugin (named __Files__) and thus can be disabled in Obsidian settings - Some community plugins (like __MAKE.md__) also disable the File Explorer by default - See obsidinan developer console for detailed error message - To fix the problem, enable the File Explorer (in Obsidian or in the community plugin responsible for hididing it) -- ![Sorting not applied](./docs/icons/icon-not-applied.png) Plugin enabled but the custom sorting was not applied. +- ![Sorting not applied](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-not-applied.png) Plugin enabled but the custom sorting was not applied. - This can happen when reinstalling the plugin and in similar cases - Click the ribbon icon twice to re-enable the custom sorting. -- ![Static icon](./docs/icons/icon-mobile-initial.png) Only on large-screen mobile devices like iPad. +- ![Static icon](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-mobile-initial.png) Only on large-screen mobile devices like iPad. - Plugin enabled. but the custom sorting was not applied. On small-screen mobile devices (phones) the icon is static: -- ![Static icon](./docs/icons/icon-mobile-initial.png) The icon acts as a button to toggle between enabled and disabled. Its appearance doesn't change +- ![Static icon](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/icons/icon-mobile-initial.png) The icon acts as a button to toggle between enabled and disabled. Its appearance doesn't change - Click to enable and apply custom sorting or to disable custom sorting - To get notified about custom sort plugin state, enable the mobile-specific notifications in plugin settings diff --git a/docs/manual.md b/docs/manual.md index a712be5..642868a 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -1,6 +1,6 @@ > Document is partial, creation in progress -> Please refer to [README.md](../README.md) and [advanced-README.md](../advanced-README.md) for more usage examples -> Check also [syntax-reference.md](./syntax-reference.md) +> Please refer to [README.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/README.md) and [advanced-README.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/docs/advanced-README.md) for more usage examples +> Check also [syntax-reference.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/syntax-reference.md) --- Some sections added ad-hoc, to be integrated later @@ -11,7 +11,7 @@ Some sections added ad-hoc, to be integrated later Do you want to have a nice-looking horizontal separators in File Explorer like this? -![separators](./img/separators-by-replete.png) +![separators](https://raw.githubusercontent.com/SebastianMC/obsidian-custom-sort/master/docs/img/separators-by-replete.png) If so, head on to [Instruction and more context](https://github.com/SebastianMC/obsidian-custom-sort/discussions/57#discussioncomment-4983763) by [@replete](https://github.com/replete) diff --git a/docs/syntax-reference.md b/docs/syntax-reference.md index e5c0771..fe8e12f 100644 --- a/docs/syntax-reference.md +++ b/docs/syntax-reference.md @@ -1,6 +1,6 @@ > Document is partial, creation in progress -> Please refer to [README.md](../README.md) for usage examples -> Check [manual.md](./manual.md), maybe that file has already some content? +> Please refer to [README.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/README.md) for usage examples +> Check [manual.md](https://github.com/SebastianMC/obsidian-custom-sort/blob/master/doc/manual.md), maybe that file has already some content? # Table of contents