Some initial ideas for the "Architecture" subheading:
Joplin is primarily written in TypeScript, a more robust form of JavaScript, and runs in Node.js, which allows JavaScript to be used outside of a browser environment. Joplin's codebase uses Yarn, npm, and Cocoapods to manage its dependencies. Its graphical user interface is written using React, a cross-platform framework that allows the much of the same code to be used on all of the platforms on which Joplin currently runs. On Android and iOS, Joplin uses ReactNative, and on macOS and Windows, it uses React to build an HTML interface that runs in Electron.
After this, there could be a list of the folders in the root directory of the repository, with a short explanation of what each of them contains.
The Joplin repository is organized as follows:
Note: the organization of this folder leaves something tobe desired. It might make sense to make high-level divisions between application icons, toolbar icons, assets used by the Joplin website, and assets used in App Store listings.
- joplin / CliClient contains code used in the Joplin command-line client.
Question: do the GUI clients use anything from the CliClient directory? If so, it might be better to name it something like "JoplinFramework" and separate out the files solely pertaining to the command-line interface.
-
joplin / Clipper contains code used by the Joplin web-clipper browser extensions.
-
joplin / ElectronClient contains code specific to platform integration on macOS and Windows.
-
joplin / Modules contains... a mish-mosh?
"Modules" seems like it would contain code shared between the different clients, ie "JoplinFramework" as described above.
-
joplin / ReactNativeClient contains code specific to platform integration on Android and iOS.
-
joplin / Tools seems like another mish-mosh?
-
joplin / docs looks like it's literally the website.
If your intention is for the documentation in full to be mirrrored between the GitHub repository and the website, it might be worth looking into a way to parse Markdown files and automatically publish them as HTML. It looks like someone has developed a way to do this, albeit somewhat manually.
-
joplin / patches ...I don't understand the contents of this folder.
-
joplin / readme seems to contain a somewhat assemblage of Markdown files, some of which seem to be drafts or components of the main README.md and which generally don't seem interlinked.
Honestly it feels like this folder should be called "Documentation"; it should be built with aggressive interlinking; and much of it should be built automatically as the website. If website and documentation assets (ie images) are stored in this directory, one way to keep things organized could for each page to have its own folder, with any assets stored alongside a nested README.md file (since my understanding is that GitHub automatically renders Markdown files with this name (and this name only) as HTML below the directory listing.
However, in the long run, it could work better to organize the documentation into the same directories as the code to the greatest extent possible. Some Markdown pages might not make sense to file this way, and those pages could be organized under "Website" or "Meta", though as much as possible the Markdown documentation should remain inline.
FWIW, there is an nmp package called TypeDoc that can automatically generate documentation directly from TypeDoc comments, and, yes, someone has made a Markdown plugin for it. It could make sense for the Joplin repository's build process to automatically run TypeDoc just like it currently runs unit tests, so that the documentation is always up to date.
1 Like
