State of Sublime Text Documentation

[vwheeler63]

@milkman wrote:

and documenting everything I have learned so far that isn’t documented elsewhere.

Which license applies to your docs (http://crystal-clear-research.com/docs/quickrefs/sublime_text/ ), I only see a copyright notice. Asking as there might be things that could be added to https://docs.sublimetext.io/ (I did only see that you seem to have written quite much). If you could put it under a free license, your work could be reused.

---

Hi, @milkman!

Good question. I haven’t decided yet. I started writing it just for my own use as a quick reference, but there is SO MUCH to Sublime Text and so much that I have yet to learn… And I’ve been kind of tinkering with the idea of turning it into a book (I need the income!). On the other side of that coin, I have most certaintly “spring-boarded” from the documentation that does exist, and most especially from @OdatNurd’s awesome video collection, so in my opinion, it has been a collaborative effort thus far, with the exception of things I had to dig in on myself to discover (e.g. the Viewport page, and a handful of details about the key-binding context “key” values [test names]—and there is a bunch more, but I’ll skip the details).

Please accept the following in a loving, team-member like tone and intention:

---

One thing is for sure, the current documentation arrangement is a liability in my opinion. Currently (not counting my work) there are 4 places an ST user has to go to to learn something. I personally do not like separating the “Guide” from the “Reference” in the community docs when it means that content is in 2 places (either duplicate or spread out). Example: the “binary_file_patterns” element from a .sublime-project file documented in the Guide, whereas it belongs in this table in the Reference. Things like this make it difficult and inefficient to use.

If I could only show you a copy of the original Lotus 1-2-3 (early, brilliantly-successful spreadsheet software written by Lotus Development Corporation in Assembly Language and produced an .exe that was about 120KB, enough to still have some room on a 128KB floppy disk for a few spreadsheets). One of the real GOLD NUGGETS from that work was its user’s manual. It had a relatively small orientation section in the beginning where most of the main topics were covered briefly to get you started, and then the MAJOR part of the manual was a reference section where the topics were organized in logical order and each one covered THE FULL TOPIC—nothing was left out. So when you studied, say the topic of “macros”, beginning to end, you were a MASTER of Macros. There was nothing more to learn. And each reference topic contained:

1. Introduction / orientation material introducing the topic, answers “the basic questions”, and how it relates to the rest of the system.
2. Presenting the WHOLE topic, A-Z, in logical and complete sections in a sequence where later sections built on earlier ones.
3. Repeat #2 until entire topic was covered.
4. Repeat 1-3 for next topic.
5. No topics left out, no topics only covered partially.

Each topic had its own TABBED section (literal thumb tabs in the manual so you could get to its content quickly without going to the table of contents). Nothing was left out.

And that documentation was a KEY LINK in propelling Lotus 1-2-3 into a leadership position in the spreadsheet market.

The most important takeaway from this: IT WAS ALL IN ONE PLACE (the reference section), including the introduction, all the way to through to the highly advanced stuff. The intro section did not take anything away from the reference section—it just gave introductory material for orientation and bare basics, while ALL of that was present in the reference section in complete detail, so if you were already oriented, you could start on a new topic in starting in the reference section and not miss anything.

If I contribute a great effort to something—I want THAT to be the result—not just more scattered documents that leave a new ST user with 4 places to look for each topic.

I wish I could get in touch with the person or group that could make the decision to make that happen. I’d be ALL IN. Do you know who that is? Thoughts?

Kind regards,
Vic

P.S. Judging from the number of daily installs of PackageControl Package, I’m guessing that Sublime HQ is making an absolute MINT. I’m a highly qualified writer (and a firmware/software developer between projects) and would absolutely ADORE an opportunity like bringing all the documentation together in 1 place and pushing it forward to be both complete and up-to-date with build 4200… while keeping my bills paid. And fix the sometimes too-sparce API documentation… Is Sublime HQ in a position to give that a green light? Id’ sure like to talk to the right people to make that happen. I could work on it full time if paid, and I would not ask a lot…

[Innovator]

Can I suggest that you start by placing documentation in CherryTree. An XML based hierarchical notes editor.

https://www.giuspen.net/cherrytree/#:~:text=A%20hierarchical%20note%20taking%20application,(currently%20old%20and%20discontinued).

You can drop various syntaxes into codeboxes to execute … all in one place as you request. There are advantages in the XML code. The *.ctd files can be opened in Subl txt as XML. Cherrytree content at node level can be accessed via command line. Hit F1 for On Line Manual. I shall be using CherryTree as a container to send/receive from Claude allowing closer marriage with Subl text. As a writer you will also see the advantage of using quarto leading to Jupyter note books. tools such as Scribus can be held in CherryTree … all XML. And able to be wrapped in XBRL for audit purposes if we suspect bad actors.

When you write "So when you studied, say the topic of “macros”, beginning to end, you were a MASTER of Macros. " you are referring to context vectors.That is what I mean by getting away from keys memory. It is the context we need to access.

P.S. I simply exported the docs and imported into CherryTree as a crude start. Preferences need tuning and sections broken into hierarchical nodes with executable code examples. But it is in one container and other guides can by imported and even packages. Proof of the pudding …

[vwheeler63]

Hi, @milkman !

Is there a “who’s who” of people who are directly involved with ST documentation? Is it possible to communicate with the core of ST HQ?

Looking forward to your reply,
Kind regards,
Vic

[deathaxe]

TL;TR: Everything on docs.sublimetext.io is purely community driven open source free of charge content. License can be found in underlying github repo https://github.com/sublimetext-io/docs.sublimetext.io

Any high quality contributions are wellcome and appriciated, I guess.

SublimeHQ seems primarily being represented by @bschaaf at the moment.

[vwheeler63]

Thank you, @deathaxe.

[robbd]

As someone who has explored many corners of Sublime over the past ~6mo (releases forthcoming!), I could not agree more with the opening statement: the current documentation is a liability at best.

The official docs seem fine for final users, though quite retro/basic compared both to modern standards like uv or pydantic and to effective users of Sphinx/ReadTheDocs like MyST or more-itertools. Sublime’s whole value proposition lies in its minimal baseline paired with rich customization & extension capabilities so ‘fine’ isn’t sufficient in this case IMO, but that’s not my main point here:

For plugin/syntax devs, “fine” quickly becomes “far from sufficient”. Your site looks great Victor, and I suspect you can share my frustrations with trying to haphazardly infer things from other plugins, hopefully avoiding any outdated approaches. Even that is much harder than it should be since most plugins are in zip files! Like, I shudder to think how many hours I spent developing packages before I learned about PackageDev (which is basically a prereq for doing so efficiently).

Separately/more fundamentally, the “community docs” situation is extremely offputing – I imagine many thousands of potential users have been driven back to VSCode or on to Warp/Zed when they search “sublime how to set hotkeys” and find two competing versions with an unclear connection. The community docs are obviously incredible for what they are, and I appreciate all the work that has gone into them! The problem is rather with SublimeHQ’s choice to not embrace that project and join the two. It’s not like their docs are valuable IP that others might steal, after all…

Really this raises an underlying question that has slowly reared its head for me as I learn more about Sublime: what is SublimeHQ? Hell, who is SublimeHQ? They release software intermittently with non-trivial improvements (and hopefully will be launching the py313 host soon (even if its 567 days late and counting…)) and made at least $99 this year from me, so they’re not a ghost corporation. But;

1. …the founder–Jon Skinner–is an effectivley-anonymous “Software Engineer” who’s been running Sublime for basically his whole career (18.5 years so far), and the company’s LinkedIn has basically 0 information and mostly anonymous members.

2. As I tackled various parts of the Sublime ecosystem, I began to notice a few names pop up over and over again. deathaxe and fichtefoll are by far the most prolific AFAICT, but there seem to be quite a few people who–like me–are weird enough to dedicate their free time to improving their text editor. Hell, the LSP plugin has setup a whole new nested ecosystem within sublime text, complete with development frameworks and its own doc! Community involvement is always great, but the employee:rando ratio here seems oddly close to infinity…

3. On that note, the PackageControl situation is identically baffling and offputting. The original PackageControl dev supposedly made two Sublime packages part of his job title at some contracting firm, which implies that he wasn’t affiliated with the company itself either. Isn’t that… strange? In the era of supply chain attacks, who’s checking every package? All it takes is one bad package leading to a major cyber incident for Sublime Text to be banned across FAANG and thus shuttered permanently…

SublimeHQ is of course smaller than Microsoft, and it’s not a bad thing to have community involvement.

Like you Victor, I really regret if any of this comes across as accusatory or dismissive; obviously I love SublimeText, and want it to succeed even more now that I’ve sunk so much time into learning how to extend it. And I certainly don’t care if the owners and/or proprietors of the software prefer privacy online. But… well, I’m worried, to be frank. Worried that my favorite piece of software is slowly, secretly being abandoned

TL;DR: Does anyone have links on SublimeHQ’s story, or perhaps even the time and energy to share a short (partial) explanation here? Why are they so hands-off? Has anyone talked to/know the handle of Kari Nicholas, their 13-year comms exec?

P.S.

Judging from the number of daily installs of PackageControl Package, I’m guessing that Sublime HQ is making an absolute MINT.

I was gonna correct you since most people don’t pay, but after some research: the text editor market is supposedly sized ar $2.5B USD, and 10% of software developers reported used Sublime “regularly” in 2025. Assuming devs are only half of the market (very generous) and that Sublime users are 1/10th the value of VSCode users (very generous), that’d still be… $125M USD in annual revenue (!!!)

P.P.S. Sorry to attempt to hijack your thread Victor – will check out your docs regardless . Been writing this post in my head for months, I think!

[Innovator]

Worried that my favorite piece of software is slowly, secretly being abandoned

This reminds me of Atom and the forum which I used until it was “sunset” by GitHub in favour of VS. Perhaps dump Subl forum material onto the Wayback Machine from time to time.

[vwheeler63]

Hi, Robb! ( @robbd )

I enjoyed reading every paragraph, and you brought forth some of my own thoughts that I had not yet expressed. A couple of things that bear sharing:

1. I recently had a 20-minute look-around on the Sublime Discord channel, and I found regular announcements of major and sub-releases (between Sublime Text and Sublime Merge) are coming out regularly, which tells me there is some very effective software development going on. The last 6 months have seen much attention on Sublime Merge, but just in the last month or so there have been (I believe) 3 dev releases of Sublime Text! 4205 is out now as of just a few days ago!

2. As of Dev version 4203 (if I remember correctly), Python 3.8 has been upgraded to not 3.13 but 3.14! A big leap of faith but apparently 3.14 is seen as stable enough to trust now. I am running it on my system now and found a bug in one of my Packages as a result of testing it out. (And a patch for that bug just went into a new version update for my package BoxDrawing, released as of yesterday afternoon USA Mountain Daylight time.)

3. Just before build 4200 was released, I reported a bug and it was fixed within 24 hours and accommodated the 4200 build. (Speaks a lot towards “someone, if not a team (?), is very active behind the scenes”.)

4. Having paid close attention to some of the more dedicated contributors (you named 2 of them), I find that most of the bugs I have reported have gotten prompt attention, which I find very encouraging! (Thank you @deathaxe and @FichteFoll and several others, you know who you are.) And I will say that the fact that there IS community documentation, and that it is in as good a shape as it is in – is a wonderful statement about their dedication and commitment to improving the documentation situation. And they have done so to quite an extent, within available means, and for this, commendations are certainly in order (even though the whole scene put together generates frustration from those who know how good it CAN be, and sees the potential of this editor).

5. I have put one heck of a lot of work into that document thus far—passing 1000 hours by this point. I started knowing nothing back in May of 2025 and everything I learned that wasn’t already well documented, I wrote up for myself in a way that hopefully can be well understood by myself 2 years from now, and hopefully others. And in some cases, I have tried to bring together a COMPLETE presentation for a number of sub-topics. 90% of the detailed stuff was done through self-learning and testing, where there were just “hints” provided either in the documentation or in the API (which took a lot of time—frustrating when in an ideal situation it would be findable in documentation).

   Example: nowhere in any Sublime Text documentation is a proper introduction to its user interface. So you can find that on my Introduction page—it serves like a reference as well as a thorough intro to ST in about 25 minutes, if you study it from top to bottom.

   Another classic example: basic editing, which I have tried to do a VERY thorough job on, and I think I have succeeded. A lot of that material is nowhere else!

   Another classic example: it look me a long time (and writing a Package surrounding it that it is not yet released) to discover that the number of variables you can include in a Snippet (including variables you create yourself) is literally unlimited for all practical purposes! I think I did a pretty good job on that too, including everything I have learned so far.

   Another classic example: a very important caveat for Sublime Text Packages that have multiple modules, some in subdirectories below the root of the Package—a caveat that does not apply to normal Python packages, but it does when they are under Sublime Text, and it explains why. This one took about a week of study and learning and testing, plus everything I have learned after that first week, probably 10-12 days total.

   Another classic example: Viewports.

   You would think I was retired or had nothing better to do, but in fact, all of this is driven by 2 things: my enthusiasm for the editor, and the sheer will because of that enthusiasm to carve out time for it.

6. I maintain that it’s time (because I have grown past my impatience and the genuine need for it) for all this work to come together in one LARGE document in ONE PLACE (preferably at the official docs site) that covers everything, with AMPLE due credit for all who have contributed knowledge and wisdom thus far (and if I had my way, a BIG early surprise Christmas bonus for them in the mail). (Which includes such wisdom when it is conveyed via feedback on GitHub package submissions.) This is my opinion, and I strongly suspect it would boost the Sublime Text market to the sky, and make that income graph tilt up to near vertical…

7. I think I may have cleared up some of the confusion surrounding releasing new Packages to the ST community here. Why don’t you read it and let me know, I’d appreciate the feedback, especially if you find it is missing anything.

[bschaaf]

@vwheeler63 From a quick look that documentation it seem to be well written, thanks for putting in all that effort. We’ll be discussing your proposal internally.

@robbd Sublime HQ is a small business in Sydney, Australia, with 5 employees. You can read a bit about how things started on our blog: https://www.sublimetext.com/blog/articles/2007/11

We only have two products, maintaining and improving them is how we make money. Abandoning them is directly opposite our best interests.

Has anyone talked to/know the handle of Kari Nicholas, their 13-year comms exec?

Kari is not on the forum or discord. She is contactable through email: support@sublimetext.com.

I was gonna correct you since most people don’t pay, but after some research: the text editor market is supposedly sized ar $2.5B USD, and 10% of software developers reported used Sublime “regularly” in 2025.

That page also says that the top “companies” are VS Code, nodepad++, sublime, brackets, UltraEdit, etc. None of which are companies, all of which except for ST are free or open source. It also says 60% of editors provide mobile apps, which is just a lie. So I wouldn’t believe anything on that page… Sublime HQ doesn’t have anywhere near that revenue.

[vwheeler63]

Dear Mr. Schaaf,

Outstanding! I hope it is considered carefully how much ST and its customers can benefit from having everything in one place, all the way down to the nitty gritty details when they help Package developers. I would go out of my way to make it work!

Having just gone through my whole learning curve thus far in the last 11 months, I feel fairly strongly that the success of the software is driven a great deal by how quickly its new users can reach success with it, and if it takes too long, they start looking elsewhere. I am confident that ST is losing income to exactly that circumstance. How much, of course, is not measurable, except over time after a change is made (e.g. with an income graph). In any case, I much appreciate you and Jon’s time and consideration.

It should also be noted that I have been updating that document (site) almost daily—every time I learn details that I didn’t know before.

Kind regards,
Vic