Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/200ok-ch/organice

An implementation of Org mode without the dependency of Emacs - built for mobile and desktop browsers
https://github.com/200ok-ch/organice

emacs org-mode productivity progressive-web-app project-management

Last synced: 28 days ago
JSON representation

An implementation of Org mode without the dependency of Emacs - built for mobile and desktop browsers

Host: GitHub
URL: https://github.com/200ok-ch/organice
Owner: 200ok-ch
License: agpl-3.0
Created: 2019-08-23T06:30:56.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2024-01-06T17:45:43.000Z (10 months ago)
Last Synced: 2024-04-14T11:54:41.854Z (7 months ago)
Topics: emacs, org-mode, productivity, progressive-web-app, project-management
Language: JavaScript
Homepage: https://organice.200ok.ch/
Size: 10.3 MB
Stars: 2,334
Watchers: 38
Forks: 140
Open Issues: 113
Metadata Files:
- Readme: README.org
- Changelog: changelog.org
- Contributing: CONTRIBUTING.org
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

stars - 200ok-ch/organice - built for mobile and desktop browsers (HarmonyOS / Windows Manager)
jimsghstars - 200ok-ch/organice - An implementation of Org mode without the dependency of Emacs - built for mobile and desktop browsers (JavaScript)

README

# -*- org-adapt-indentation: nil; fill-column: 70; -*-
#+title: organice documentation

#+html:

organice - /'ɔ:gənaɪz/

#+html:

organice organizes Org files nicely!

#+html:

* General
:PROPERTIES:
:CUSTOM_ID: general
:END:

# REPO_PLACEHOLDER

# INFO: We're using inline =#+HTML= notation in favor of the much more
# readable =#+BEGIN_EXPORT html= notation, because GitHub uses legacy
# Org parsers and wouldn't render the latter. GitHub would render
# the legacy notation =#+BEGIN_HTML= which will not be properly
# exported from Emacs, because it's legacy. Hence the glorious
# solution: Write all HTML in one line.

#+HTML:

[[https://organice.200ok.ch/documentation.html][Documentation]]

Community chat:
- #organice on IRC [[https://libera.chat/][Libera.Chat]]
- [[https://matrix.to/#/#organice:matrix.org][#organice:matrix.org]] on Matrix

Creating and maintaining organice is made possible by all the
volunteering [[https://github.com/200ok-ch/organice/graphs/contributors][contributors]] and [[https://github.com/sponsors/200ok-ch][sponsors]]. If you enjoy using organice,
and want to sponsor the development of Free and Open Source software,
you can do so with [[https://github.com/sponsors/200ok-ch][Github Sponsors]] and [[https://www.patreon.com/200ok][Patreon]].🙏

** Sponsors

#+HTML:

And one anonymous sponsor.

** What does this project do?
:PROPERTIES:
:CUSTOM_ID: what-does-this-project-do
:END:

organice is an implementation of [[http://orgmode.org/][Org mode]] without the dependency of
[[https://www.gnu.org/software/emacs/][Emacs]]. It is built for mobile and desktop browsers and syncs with
[[https://www.dropbox.com/][Dropbox]], [[https://gitlab.com/][GitLab]], and [[https://en.wikipedia.org/wiki/WebDAV][WebDAV]].

At [[https://200ok.ch/][200ok]], we run an instance of organice at https://organice.200ok.ch,
which is open for anyone to use! organice does not have a back-end
(it's just a front-end application, which uses different back-end
storage providers). We don't store any kind of data on our servers -
we also don't use analytics on organice.200ok.ch.

[[https://raw.githubusercontent.com/200ok-ch/organice/master/images/screenshot-overview.png]]

** Why is this project useful

Emacs is great, but it's desktop software. For users who want to
access or edit their Org mode files whilst on the go, organice is a
great choice.

** Introduction

If you prefer a video to some text, we've got you covered! For
[[https://emacsconf.org/2019/][EmacsConf 2019]], we've created a 10 minute introductory video into the
rationale and usability of organice.

#+html:

You can watch it on:

- [[https://www.youtube.com/watch?v=aQKc0hcFXCk][Youtube]]
- [[https://media.emacsconf.org/2019/05.html][emacsconf.org]]

* Installation
:PROPERTIES:
:CUSTOM_ID: installation
:END:

organice is a web application. You can use it from any browser. On iOS
and Android, you can install organice to your homescreen. When started
from there, it will run in full-screen as a Progressive Web
Application (PWA) which will add offline capabilities (see chapters
[[#progressive_web_app][progressive web app]] and [[#offline_support][offline support]]).

To install organice to the homescreen follow these platform specific
instructions:

- *iOS:*

Open organice in Mobile Safari. Tap the "share" button and select
"Add to Home Screen".

- *Android:*

The exact procedure may differ depending on your browser and Android
version. If you discover improvements to the following procedure,
please [[https://organice.200ok.ch/documentation.html#contributing][let us know]]!

First open the organice web page in your mobile browser.

- On Chrome, tap the "menu" button (three vertically stacked dots)
and select "Add to homescreen".

- On Firefox, "menu" button (three vertically stacked dots)
and select "Install". If you don't have that option, you may have
one to tap the home icon with the plus sign inside it which
is immediately to the right of the URL in the address bar.

- Other browsers may have a similar procedure to one of these.

At this point, most browsers will present a popup banner with the
option to "Add to homescreen" or "Install".

By default, when you start organice, it will display your root file
directory. If you prefer to display a specific Org file instead, you
can select it in the [[https://organice.200ok.ch/settings][file settings]].

* Usage
:PROPERTIES:
:CUSTOM_ID: usage
:END:
** Current restrictions/expectations of organice

"Current" means we're working hard on removing the following
restrictions and expectations.

- organice understands only a few in-buffer settings (see [[#in_buffer_settings][Supported
in-buffer configuration]])
- Other in-buffer settings are imported and re-exported but are not
editable with organice.
- Other content before the first headline is imported and re-exported,
but invisible and currently not editable with organice.
- After potential in-buffer settings, your Org file _has to_ begin
with a headline.

Apart from these restrictions, organice is very robust in reading and
editing your Org file and not breaking any of it. We're having users
with 10'000 lines in their files including all kinds of native Org
functionality - and even these files work just fine in organice!

Generally, when working with distributed Org files, we're recommending
to put them under version control and to check for bugs and racing
conditions between clients.

Please [[https://github.com/200ok-ch/organice/issues/new][file an issue]] if you find additional restrictions, expectations
or bugs that you wouldn’t have expected.

*** Background information
:PROPERTIES:
:CUSTOM_ID: background-information
:END:

organice has [[https://github.com/200ok-ch/organice/blob/master/src/lib/parse_org.js][a custom parser]] for Org files. It works quite fine and
has unit tests to prove it. One of the quality goals for the parser is
that when it parses and re-exports an Org file, it should not change
the original file. Not seeing unrelated diffs is important for the
productivity of the user. It sounds trivial, but lots of alternative
products do not live up to this expectation.

Writing a parser for a complex syntax like Org mode in custom code is
hard. Therefore, we are in the process of implementing a proper EBNF
based parser and a set of tests behind that. If you're interested,
please check it out: [[https://github.com/200ok-ch/org-parser]]

The strategy we're using with regard to the parser is this:

- Keep improving the existing custom parser for new features and make
bug fixes as long as the new one isn't ready.
- In parallel, work on the new one until there is feature parity
between both parsers.
- When the new one is finished, integrate it into organice.

** Progressive Web App
:PROPERTIES:
:CUSTOM_ID: progressive_web_app
:END:

organice can run as a PWA (Progressive Web App) - see the
[[#installation][installation instructions]] and does have offline
support. From your home screen, organice will start up in full screen
and it will use a [[https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API][Service Worker]] to cache the application. On a
desktop browser, the Service Worker will be used automatically. This
is implemented using the Create React App [[https://create-react-app.dev/docs/making-a-progressive-web-app/#docsNav][Progressive Web App]]
functionality which enables the following features:

- All static assets are cached so that organice loads fast on
subsequent visits, regardless of network connectivity.
- Updates are downloaded in the background.
- organice works regardless of network state, even if offline.
- On mobile devices, organice can be added directly to the user's home
screen, app icon and all.

Following that, if you start modifying your Org file when offline,
organice will recognize that you are offline and queue up the
synchronization until you are online again.

organice also understands when it's local Org file is outdated
compared to the upstream file and will ask you what you want to do -
pull the one from the synchronization back-end, push the one from
organice or cancel. This happens when you made changes to your file on
at least two machines at the same time without synchronizing them in
the meantime. For this, we recommend putting your Org file under
version control which is the idiomatic solution for changing text
based files on multiple machines in parallel.

** Offline Support
:PROPERTIES:
:CUSTOM_ID: offline_support
:END:

Additionally to the offline support provided through implementing
organice as a [[#progressive_web_app][progressive web app]] (see above) organice has the
following offline capabilities:

- Every file opened in organice will automatically be cached on your
device (through =localStorage=).
- When visiting the file, again, it will immediately be loaded from
the local storage and then loaded from the remote back-end.
- That makes loading and switching between files instant _and_ gives
you the ability to work on multiple files when being offline.

** Multi file support
:PROPERTIES:
:CUSTOM_ID: multi_file_support
:END:

Agenda, Search, Task List, Refile and Capture Templates have the
ability to work on multiple files. You can adjust the behavior for
these on a file per file basis by creating "file settings" in the
settings menu. Multi file support works well with the offline
capabilities documented in [[#progressive_web_app][progressive web app]] and [[#offline_support][offline support]].

* Customization
:PROPERTIES:
:CUSTOM_ID: customization
:END:

** General

Since organice implements Org mode, one might wonder if we plan to
duplicate the Emacs configuration strategy. In Emacs Org mode, there's
more than [[https://orgmode.org/worg/org-tutorials/org-customize.html][650 variables for customization]] - and on top of that,
there's often two ways to configure things:

1. Using elisp
2. Using [[https://orgmode.org/manual/In_002dbuffer-settings.html][in-buffer settings]]

Modifying Org behavior using elisp (variables) is certainly mighty and
powerful. However, the goal of organice is not to clone Emacs in full.
In fact, it could be argued that this is not possible. Emacs being a
LISP machine has inherent power that cannot be brought to a web
application. Instead, the goal is to make Org mode accessible on
smartphones and for non-Emacs users. For both use-cases, elisp
variable configuration is not an idiomatic or ergonomic option.

organice implements this customization strategy:

- Use in-buffer settings where appropriate
- Build custom and mobile friendly user interfaces where appropriate
- For example [[#capture_templates][capture templates]]

** Supported in-buffer configuration
:PROPERTIES:
:CUSTOM_ID: in_buffer_settings
:END:

*** In-buffer settings

- =#+TODO=
- =#+TYP_TODO=
- =#+SEQ_TODO=

*** =#+STARTUP:= options

- =nologrepeat=: Do not record when reinstating repeating item

*** Drawer properties
:PROPERTIES:
:END:

- =logrepeat= and =nologrepeat=: Whether to record when reinstating repeating item

#+BEGIN_EXAMPLE
:PROPERTIES:
:LOGGING: logrepeat
:END:
#+END_EXAMPLE

** Themes / Color scheme / Dark Mode / Light Mode
:PROPERTIES:
:CUSTOM_ID: themes
:END:

organice bundles several popular color themes, each in =light mode=
and =dark mode=.

If you've set up a color scheme preference in your operating system,
organice will honor this preference. It uses the
=prefers-color-scheme= media query for this. Here, you can see if your
browser supports this media query: https://caniuse.com/?search=prefers-color-scheme

If you change your color scheme preference directly within organice,
this naturally overrides your operating system preference. The color
schemes in organice are implemented in a strategy pattern, so that
adding new themes is quite easy.

These themes come bundled with organice:

*** Solarized

#+html: