And one anonymous sponsor.

organice is an implementation of Org mode without the dependency of Emacs. It is built for mobile and desktop browsers and syncs with Dropbox, GitLab, and WebDAV.

At 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.

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.

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

You can watch it on:

• Youtube
• emacsconf.org

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

• organice understands only a few in-buffer settings (see 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 file an issue if you find additional restrictions, expectations or bugs that you wouldn’t have expected.

organice can run as a PWA (Progressive Web App) - see the installation instructions and does have offline support. From your home screen, organice will start up in full screen and it will use a 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 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.

Additionally to the offline support provided through implementing organice as a 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.

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 and offline support.

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 650 variables for customization - and on top of that, there's often two ways to configure things:

1. Using elisp
2. Using 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

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:

For some customizations, organice exposes a mobile friendly user interface. Please find them in the 'settings' view (cogs icon in the header on the right).

You will need a version of the Node.js engine installed which fulfills the requirement stated in package.json. If you don't already have this installed, it is recommended to install it via nvm. The organice repository already contains an .nvmrc file, so once you have nvm installed, the following commands should be sufficient:

nvm install
nvm use

When you're developing a new feature and you want to manually test it, it's best to check it out in a Desktop browser and on your smartphone. This is how you do that:

Apart from the popular choice of console.log-debugging, it's easy to use Chrome or Chromium for debugging tests.

Place a debugger; statement in any test, then run:

yarn test:dbg

This will start running your Jest tests, but pause before executing to allow a debugger to attach to the process.

Open the following in Chrome:

about:inspect

After opening that link, the Chrome Developer Tools will be displayed. Select inspect on your process and a breakpoint will be set at the first line of the react script (this is done to give you time to open the developer tools and to prevent Jest from executing before you have time to do so). Click the button that looks like a "play" button in the upper right hand side of the screen to continue execution. When Jest executes the test that contains the debugger statement, execution will pause and you can examine the current scope and call stack.

The "Create React App" upstream docs for this feature are here: https://create-react-app.dev/docs/debugging-tests/

The productive reference instance of organice is deployed to https://organice.200ok.ch/. On merging a pull request to master, code and documentation are automatically deployed to production.

For more complicated features (aka epics) that require more than one pull request, there is a reference stage instance on https://staging.organice.200ok.ch/. When working on epics, we follow the popular nvie git branching model in that we successively create feature branches against develop until the epic is finished. On merging a pull request to develop, code and documentation are automatically deployed to stage.

Please see our contributor guidelines and our code of conduct.

When discussing new UX, it is often helpful to add a mockup to the discussion to ensure that everyone is on the same page. When a new contributor suggests a UX change and it's not trivial, we will ask to include a mockup to the issue.

Of course, you're completely free to create such a mockup with whatever tool you feel comfortable with. A scan of a pen and paper will do, using Inkscape or Illustrator is nice and so on. If you don't have a personal preference, and want to get going quickly, you can use the mockup included in this repository. Find the file /doc/mockups/organice-mockup.excalidraw and upload it to the open source sketching tool excalidraw.com. There, make any changes you like, and export the result as either .png or .excalidraw and attach it to the original issue.

NB: The .excalidraw file can also be opened by any SVG capable tool like Inkscape.

First create the production build locally: yarn run build Note: Creating a build will actually make your REACT_APP_* variables from the .env file available under process.env even though it'll be a front-end application.

And then upload to your web-server. Here's a sample script for your convenience:

HOST='your_ftp_server_host'
USER='ftp_user'
PASSWD='ftp_password'

lftp $HOST <<END_SCRIPT
user $USER $PASSWD
mirror -R build/
quit
END_SCRIPT
exit 0

The reference instance (https://organice.200ok.ch), for example, is deployed via FTP. The full build script is in bin/compile\_and\_upload.sh.

organice is also available as a Docker image.

The docker image recognizes a couple of environment variables. For example REACT_APP_WEBDAV_URL prefills the URL field in the WebDAV signin form. See docker-compose.yaml for an example how to use it.

A full list of such environment variables can be found in .env.sample.

The prefix REACT_APP_ has to be replaced with ORGANICE_. The naming should be pretty self explanatory.

Assuming, you have an account and have installed the command line tools, deployment is as easy as:

heroku create
heroku config:set ON_HEROKU=1
git push heroku master

Whilst organice is a true Single Page Application (SPA) and therefore has no back-end whatsoever, this does have an implication for deployment with regard to routing. For routes like example.com/foo to work, we need a little something extra. Within the context of a running SPA, /foo would be matched by the React Router and the proper page would be rendered by JavaScript. When initially requesting a route like that from the web server itself, the SPA is not running yet and the web server itself wouldn't find a file called /foo. It would return a 404. The whole topic is explained in depth in this SO answer: https://stackoverflow.com/a/36623117

For https://organice.200ok.ch we've opted to:

• Use the modern HTML5 history API with BrowserRouter
• Not configure a back-end for isomorphic routing, because it would complicate application and deployment unnecessarily (SEO is a non-issue for organice)
• Use good old Apache Webserver for hosting the compiled static assets

Therefore configuring a catchall is as easy as setting up a .htaccess file in the root of the organice folder containing:

RewriteEngine On
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
RewriteRule ^ - [L]

RewriteRule ^ /index.html [L]

N.B.: If you're using WebDAV as a sync back-end, and the RewriteRule is allowed to apply to a WebDAV directory, it will break PUT requests to upload new files! Here's documentation on how to configure both features together correctly.

Before starting work on organice, @munen (the original maintainer) used Beorg and donated to it multiple times, because he was very happy to have a good option to access Org files on my phone with it.

The important differences to him were:

• organice is FOSS which is very much in the spirit of Org whilst Beorg is proprietary
• organice is web based, so there is no lock-in to a specific device or OS

organice has a shared history with org-web. In fact, it is a friendly fork. organice differs from org-web in that:

• organice is a community driven project. See our
  • Code of conduct
  • Contributing guidelines
  • Community chat: #organice on IRC Libera.Chat, or #organice:matrix.org on Matrix on Matrix
• organice has the commitment of a Swiss company (200ok llc: https://200ok.ch/) behind it to continually work on it.
  • 200ok has a strong track record in fostering Free and Open Source Software (https://200ok.ch/floss.html) and has co-organized EmacsConf 2019.
  • That's also why organice is Free Software (with the strong AGPL-3.0 license) whereas org-web is Open Source (with The Unlicense).
  • The continuous effort yields a certain power over time. At the time of writing this, organice has many times more commits (~2400 vs ~600) and contributors (36 vs. 9). Of course, quantity doesn't trump quality. However, many of the new contributors brought significant features and improvements, not just tiny patches.
• organice initially focused on becoming bug free - for example on parsing and exporting org files correctly.
• organice continues to evolve independently with its own feature set. For example, it has WebDAV support. For a list of all user visible changes, please see the changelog.
• organice is a project with equal focus on mobile as desktop browsers.
• org-web tracks users with Google Analytics. organice does not.
• organice has great documentation: https://organice.200ok.ch/documentation.html

Illustration credit: Vecteezy.com

organice is an implementation of Org mode (see What does this project do?). Therefore, it is important that the changes in the markup made by organice are 100% compatible with Org mode itself.

Hence, if feature X from plugin Y can be implemented in a compatible way, and the feature follows the contribution guideline, then: Yes, the feature can be added to organice.

What do we consider a bug? A bug is when an existing feature is broken.

A feature request is to ask for change in an existing feature or to ask for a completely new feature.

Hence, if your request is about a feature that Emacs Org mode has, but organice lacks, this is a feature request, not a bug.

• Ensure the bug or feature was not already reported by searching on GitHub under Issues.
• Ensure that the the bug you want to report is not known behavior by reading the readme and the wiki.
• If you're unable to find an open issue addressing the problem, open a new one.
  • If you want to report a bug or request a feature, please use the "Bug report" or "Feature request" ticket and fill out the asked for metadata.
  • If your request is neither about a bug nor feature, please do open a blank issue.

One of our quality goals is to keep the amount of issues manageable. This means that a single person has to be able to groom the backlog (review the open issues) in a reasonable amount of time.

These are the steps we take to ensure a high quality in the backlog:

1. We only keep issues open on a longer term basis that fulfill one of the following criteria:
   • Someone has committed to work on it or plausibly plans to do so in the future
   • It is a bug or regression
2. If someone files a bug or feature request which is either not clear to the maintainers or is likely not a bug, but known and documented behavior, we ask a question or link to the documentation. We also add a 'question' label to the issue. If the issue creator does not respond to the question within 5 days, we close the issue. If she does choose to respond at some point, she can re-open the issue.

If you just want to start a discussion about a new feature or a different kind of change, but do not plan on working on it yourself, you are very welcome to join the community chat: #organice on IRC Libera.Chat, or #organice:matrix.org on Matrix on Matrix. We are looking forward to seeing you there!

Alternatively, if you really want a change implemented, you can hire one of the maintainers to do the work. If you want to hire us to implement a change request, please send us an email to info@200ok.ch.

The documentation is generated from README.org and various other files. The section on building documentation explains how it is assembled.

We have good quality assurance and an established workflow. This is it:

1. Open a new GitHub pull request
2. In the form of a User Story (As <persona>, [When I <state> ], I want <something>, so that <measurable achievement>
3. Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
4. New Branch in Git
5. Naming: (feature|fix|chore)/issue-id/short-description
6. If your PR includes a substantial change to the overall architecture, consider writing an architecture decision record.
7. Develop / Test locally until tests pass
   • We use prettier-eslint to format code, which combines both prettier and eslint --fix for the best of both worlds. This repository includes .prettierrc.json and .eslintrc.yml with some configuration options that Prettier will use automatically.
   • Run yarn prettier-eslint --write to automatically format the whole codebase, or yarn prettier-eslint --list-different to see which files don't currently match the repository's style.
   • If you're using Emacs, you can autoformat your source files: https://github.com/munen/emacs.d/#auto-formatting
   • Please use eslint to ensure that your changes conform with our linting rules. You can run yarn eslint to check for rule violations, and also yarn nibble to tackle them one category at a time.
   • yarn lint will run both sets of linters.
8. Create Pull Request on Github to master
   • Check that the tests also pass on CI
9. Core Team: Merge to master, deploy and accept the Issue on Github

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

Examples of behavior that contributes to creating a positive environment include:

• Using welcoming and inclusive language
• Being respectful of differing viewpoints and experiences
• Gracefully accepting constructive criticism
• Focusing on what is best for the community
• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or advances
• Trolling, insulting/derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others' private information, such as a physical or electronic address, without explicit permission
• Other conduct which could reasonably be considered inappropriate in a professional setting

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at info@200ok.ch. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html