Ensure that your Johnny Decimal system is neat and clean.
- jdlint
- Installation/Requirements
- Usage
- File Errors
AREA_DIFFERENT_FROM_JDEXAREA_NOT_IN_JDEXCATEGORY_DIFFERENT_FROM_JDEXCATEGORY_IN_WRONG_AREACATEGORY_NOT_IN_JDEXDUPLICATE_AREADUPLICATE_CATEGORYDUPLICATE_IDFILE_OUTSIDE_IDID_DIFFERENT_FROM_JDEXID_IN_WRONG_CATEGORYID_NOT_IN_JDEXINVALID_AREA_NAMEINVALID_CATEGORY_NAMEINVALID_ID_NAMENONEMPTY_INBOX
- JDex Errors
JDEX_AREA_HEADER_DIFFERENT_FROM_AREAJDEX_AREA_HEADER_WITHOUT_AREAJDEX_CATEGORY_IN_WRONG_AREAJDEX_DUPLICATE_AREAJDEX_DUPLICATE_AREA_HEADERJDEX_DUPLICATE_CATEGORYJDEX_DUPLICATE_IDJDEX_FILE_OUTSIDE_CATEGORYJDEX_ID_IN_WRONG_CATEGORYJDEX_INVALID_AREA_NAMEJDEX_INVALID_CATEGORY_NAMEJDEX_INVALID_ID_NAME
- Why Doesn't This Check For-
- Acknowledgements
Install a fairly recent version of
Python 3; jdlint is tested to work on
Python 3.10 and up. Python 3.9 and earlier is not supported.
That's it! There are no other dependencies.
jdlint should work on Linux, OS X, or Windows.
The script itself is executable (you should be able to just run ./jdlint.py),
or you can explicitly point python at it, like python3 jdlint.py.
You'll need to pass the script the root folder of your JD-organized file system, e.g.
./jdlint.py ~/DocumentsIf you have your JDex/Index stored as files, you can improve the number of detected issues by passing that root path along as well, e.g.
./jdlint.py --jdex ~/"Knowledge/00.00 📇 System Index" ~/DocumentsThis supports three possible JDex formats:
- Single file, as specified here. Note that strict adherence to the spec is not checked, because I personally do not use this method and am lazy, so don't expect linter errors for your JDex if you use this format.
- Nested files in folders, e.g.
.
└── 00-09 System
└── 01 System Stuff
├── 01.02 A Name.md
└── 01.03 Another ID.md
- Flat files, e.g.
.
├── 00.00 System Area Management.md
├── 01.00 System Stuff Category Management.md
├── 01.02 A Name.md
└── 01.03 Another ID.md
Note that in the flat case, N0.00 is taken as the JDex entry for area N0-N9,
and AC.00 is taken as the JDex entry for category AC.
In all cases, any .md file extension will be stripped, should one exist.
A trailing area management or category management or index will also be
stripped, if one exists, to derive the "canonical" name for the area/category.
For example:
10.00 Life Admin10.00 Life Admin.md10.00 Life Admin Area Management10.00 Life Admin Index10.00 Life Admin Area Management Index.md
are all equivalent, and will lead to jdlint expecting an area named
10-19 Life Admin in your files.
For a more complete treatment of this topic, see the original post here.
This moves the expected area management zeros into the system management area.
For example, the management category for area 10-19 will be category 01,
instead of the typical 10. This increases the available number of categories
per area and makes greater use of the reserved 00-09 area.
To specify that you're using this format, pass jdlint the --altzeros flag.
This causes two changes in behavior if you are using the flat files JDex structure:
-
The linter will treat
10.00as the note for category10, and01.00as the note for area10-19, etc. -
The area management notes (
0N.00) will additionally create categories in the00-09area, for those standard zeros. -
The linter will check for optional "header" files. This is not an official Johnny Decimal thing, just something I use to visually separate notes in the JDex. They are named e.g.
10. Life Adminfor the10-19 Life Adminarea.
If you don't use them, there will be no complaints from the linter; it just ensures their names stay in sync with the area if they do already exist.
You may have files outside of IDs that have to be there; if so, you can ignore them, e.g.
./jdlint.py ~/Documents --ignore .st*This option supports some basic glob-style patterns. (It uses
PurePath.match().)
Maybe you disagree with a specific issue detected by this linter or have reason to break the rules. If so, you can disable a rule, e.g.
./jdlint.py ~/Documents --disable NONEMPTY_INBOXAsk nicely for JSON output instead!
./jdlint.py ~/Documents --jsonThese are errors that can be generated for your files. Some of them require you
passing your JDex via the --jdex argument to be detected.
An area with a differently-named JDex entry, e.g.
.
├── files
│ └── 00-09 Systme <-- This is a typo, oops!
│ └── 01 System Stuff
│ ├── 01.00 An ID
│ ├── 01.02 A Name
│ └── 01.03 Another ID
└── jdex
└── 00-09 System
└── 01 System Stuff
├── 01.00 An ID.md
├── 01.02 A Name.md
└── 01.03 Another ID.md
An area without a corresponding JDex entry, e.g.
.
├── files
│ ├── 00-09 System
│ │ └── 01 System Stuff
│ │ ├── 01.02 A Name
│ │ └── 01.03 Another ID
│ └── 10-19 Oops <-- This area has no corresponding entry in the JDex/index
│ └── 11 Cat
│ └── 11.12 ID
└──jdex
├── 00.00 System.md
├── 01.00 System Stuff.md
├── 01.02 A Name.md
├── 01.03 Another ID.md
├── 11.00 Cat.md
└── 11.12 ID.md
A category with a differently-named JDex entry, e.g.
.
├── files
│ └── 00-09 System
│ └── 01 System Stuf <-- This is a typo, oops!
│ ├── 01.00 An ID
│ │ └── Other File
│ ├── 01.02 A Name
│ └── 01.03 Another ID
└── jdex
└── 00-09 System
└── 01 System Stuff
├── 01.00 An ID.md
├── 01.02 A Name.md
└── 01.03 Another ID.md
A category that, by its number, has been put in the wrong area, e.g.
.
└── 00-09 System
├── 01 System Stuff
│ └── 01.00 An ID
└── 11 Whoops <-- This is in the wrong area
└── 11.01 Inbox
A category without a corresponding JDex entry, e.g.
.
├── files
│ └── 00-09 System
│ └── 01 System Stuff <-- This category has no corresponding entry in the JDex
│ ├── 01.02 An ID
│ └── 01.03 Another ID
└── jdex
├── 00.00 System.md
├── 01.00 An ID.md
└── 01.03 Another ID.md
An area that has been used multiple times, e.g.
.
├── 00-09 An Area <-- 00-09 has been used twice!
│ └── 01 A Category
│ └── 01.00 An ID
└── 00-09 A Reuse <-- 00-09 has been used twice!
└── 02 Another Category
└── 02.00 An ID
A category that has been used multiple times, e.g.
.
└── 00-09 System
├── 01 A Category <-- 01 has been used twice!
│ └── 01.00 An ID
└── 01 A Reuse <-- 01 has been used twice!
└── 01.02 Another ID
An ID that has been used multiple times, e.g.
.
└── 00-09 System
└── 01 System Stuff
├── 01.11 An ID <-- 01.11 has been used twice!
└── 01.11 A Reuse <-- 01.11 has been used twice!
A file that is located somewhere higher up than in an ID folder, e.g.
.
├── 00-09 System
│ ├── 01 System Stuff
│ │ ├── 01.00 An ID
│ │ └── File Outside Id <--
│ └── File Outside Category <-- All of these should only be in IDs
└── File Outside Area <--
Use the --ignore FILE_NAME option if you have files that have to be there,
e.g. .stignore is you use Syncthing.
An ID with a differently-named JDex entry, e.g.
├── files
│ └── 00-09 System
│ └── 01 System Stuff
│ ├── 01.02 A Naem <-- This is a typo, oops!
│ ├── 01.03 Another ID
│ └── 01.04 An ID
└── jdex
├── 00.00 System.md
├── 01.00 System Stuff.md
├── 01.02 A Name.md
├── 01.03 Another ID.md
└── 01.04 An ID.md
An ID that, by its number, has been put in the wrong category, e.g.
.
└── 00-09 System
└── 01 System Stuff
├── 01.00 An ID
└── 11.01 Whoops <-- This is in the wrong category
An ID without a corresponding JDex entry, e.g.
.
├── files
│ └── 00-09 System
│ └── 01 System Stuff
│ ├── 01.00 An ID
│ ├── 01.02 Missing ID <-- This ID has no corresponding entry in the JDex/index
│ └── 01.03 Another ID
└── jdex
├── 01.00 An ID.md
└── 01.03 Another ID.md
A directory was found at the area level that doesn't begin with 00-09 or the
like, e.g.
.
├── 00-09 System
│ └── 01 System Stuff
│ └── 01.00 An ID
├── 10-18 Malformed <-- This has numbers that were typo'd.
└── No ID <-- This doesn't have numbers at all
A directory was found at the category level that doesn't begin with 11 or the
like, e.g.
.
└── 00-09 System
├── 01 System Stuff
│ └── 01.00 An ID
├── 2 Malformed <-- This has numbers that were typo'd.
└── No ID <-- This doesn't have numbers at all
A directory was found at the ID level that doesn't begin with 11.12 or the
like, e.g.
.
└── 00-09 System
└── 01 System Stuff
├── 01.00 An ID
├── 01.1 Malformed <-- This has numbers that were typo'd.
└── No ID <-- This doesn't have numbers at all
An inbox (AC.01) that contains items, e.g.
.
└── 01 System Stuff
├── 01.01 Inbox
│ └── This is something you meant to sort that you never got around to...
└── 01.11 An ID
These are errors that are only generated with the --jdex argument and concern
the state of your JDex, not your organized files.
An (optional) area header with a differently-named JDex entry, e.g.
jdex
├── 00.00 System Area Management.md
├── 01.00 Life Admin Area Management.md
├── 01.03 Area Standard Zero.md
├── 10. Life Adminn.md <-- This is a typo, oops!
├── 10.00 Me, Myself, and I.md
└── 10.02 An ID.md
An (optional) area header without any corresponding JDex entry, e.g.
jdex
├── 00.00 System Area Management.md
├── 01.00 Life Admin Area Management.md
├── 01.03 Area Standard Zero.md
├── 10. Life Admin.md
├── 10.00 Me, Myself, and I.md
├── 10.02 An ID.md
└── 20. Digital Stuff.md <- There is no corresponding area
A JDex category that, by its number, has been put in the wrong area, e.g.
jdex
└── 00-09 System
├── 01 System Stuff
│ └── 01.00 An ID
└── 11 Whoops <-- This is in the wrong area
└── 11.01 Inbox
A JDex area that has been used multiple times, e.g.
jdex
├── 00-09 An Area <-- 00-09 has been used twice!
│ └── 01 A Category
│ └── 01.00 An ID
└── 00-09 A Reuse <-- 00-09 has been used twice!
└── 02 Another Category
└── 02.00 An ID
An (optional) area header that has been used multiple times, e.g.
jdex
├── 00.00 System Area Management.md
├── 01.00 An Area.md
├── 01.03 Area Standard Zero.md
├── 10. An Area.md <-- These are both for 10-19
├── 10. A Reuse.md <-- These are both for 10-19
├── 10.00 Me, Myself, and I.md
└── 10.02 An ID.md
A JDex category that has been used multiple times, e.g.
jdex
└── 00-09 System
├── 01 A Category <-- 01 has been used twice!
│ └── 01.00 An ID
└── 01 A Reuse <-- 01 has been used twice!
└── 01.02 Another ID
A JDex ID that has been used multiple times, e.g.
jdex
└── 00-09 System
└── 01 System Stuff
├── 01.11 An ID <-- 01.11 has been used twice!
└── 01.11 A Reuse <-- 01.11 has been used twice!
A file that is located at the area or category level in a nested JDex, e.g.
jdex
├── 00-09 System
│ ├── 01 System Stuff
│ │ ├── 01.02 A Name.md
│ │ └── 01.03 Another ID.md
│ └── Nor here <-- Both of these should only be in categories
└── Not here <--
A JDex ID that, by its number, has been put in the wrong category in a nested structure, e.g.
jdex
└── 00-09 System
└── 01 System Stuff
├── 01.00 An ID
└── 02.01 Whoops <-- This is in the wrong category
A directory was found at the area level in the JDex that doesn't begin with
00-09 or the like, e.g.
jdex
├── 00-09 System
│ └── 01 System Stuff
│ └── 01.02 An ID
├── 10-18 Malformed <-- This has numbers that were typo'd.
└── No ID <-- This doesn't have numbers at all
A directory was found at the category level in the JDex that doesn't begin with
11 or the like, e.g.
jdex
└── 00-09 System
├── 01 System Stuff
│ └── 01.02 An ID
├── 2 Malformed <-- This has numbers that were typo'd.
└── No ID <-- This doesn't have numbers at all
A JDEx note was found at the ID level that doesn't begin with 11.12 or the
like, e.g.
.
└── 00-09 System
└── 01 System Stuff
├── 01.00 An ID
├── 01.1 Malformed <-- This has numbers that were typo'd.
└── No ID <-- This doesn't have numbers at all
Because I didn't think of it. Open an issue and maybe it will get added!
This project has no formal affiliation with the Johnny Decimal system. The license for said system may be found here.