Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/fjwillemsen/turnaleaf

A fully offline, completely local Overleaf alternative that can switch to online Overleaf in the blink of an eye.
https://github.com/fjwillemsen/turnaleaf

Last synced: 24 days ago
JSON representation

A fully offline, completely local Overleaf alternative that can switch to online Overleaf in the blink of an eye.

Awesome Lists containing this project

README 

        
# TurnALeaf: a fully offline, native Overleaf with seamless switching





  

  

  It's time to turn over a new leaf.




## Contents



- [Motivation](#motivation)

- [Roadmap](#roadmap)

- [Installation](#installation)

- [Usage](#usage)

  - [Design Choices](#design-choices)

  - [Ideas, questions, contributions?](#ideas-questions-contributions)



## Motivation



Overleaf is a fantastic tool for writing LaTeX documents that is widely used among academics.

The main reasons it's so great:



-   user-friendly (i.e. has good defaults so you won't have to pick between a bazillion compilers and editors)

-   accessible (i.e. does not require installing five gigabytes of compiler + dependencies)

-   shareable (i.e. collaboration is easy with built-in review and chat)



However, it has one big problem: **it relies on an internet connection** to do the heavy lifting of compiling on a server, and any minor internet disruption breaks the editing process.

That is far from ideal when working on the plane on your way to a conference or on the train during your commute.



With the success of [Native Overleaf](https://github.com/fjwillemsen/NativeOverleaf), which wrapped Overleaf in a native app and added native OS integration, the most requested feature was to be able to work offline.

This requires a completely different approach that is a lot more involved than extending a website and wrapping it.



Hence, introducing... TurnALeaf!

A completely new app for writing and compiling LaTeX documents without any of the associated hurdles.

As it runs on your own device, not only are you no longer dependent on an internet connection, you also get much tighter system integration than any website can bring.

The best part? It's all free, and anyone can contribute ideas.

TurnALeaf is for academics, by academics.



## Roadmap



TurnALeaf is currently in development.

The following roadmap outlines what will be released after which features are implemented. This contains moving targets; items can be added / changed.



1. Basic functionality (0.0.1 / alpha release | 98%) 

    - [x] Base system 

        - [x] Framework (Electron)

        - [x] Bundling (Vite)

        - [x] Interface library (React)

        - [x] Styling language (PostCSS / Tailwind)

        - [x] Component library (Mantine)

    - [x] Base functionality 

        - [x] Modular interface

        - [x] Safe inter-process communication via API

        - [x] PDF rendering

        - [x] Git integration 

            - [x] Git client

            - [x] Overleaf authentication token support & storage

            - [x] Creating projects

            - [x] Fetching updates

            - [x] Pulling updates

            - [x] Pushing updates

            - [x] Removing projects

            - [x] Human-readable commit messages

        - [x] Projects overview

        - [x] File navigator

        - [x] Editor 

            - [x] Retrieval from backend

            - [x] Basic editing

            - [x] Line counter & polishing

            - [x] Tab-based editor

            - [x] Auto-saving to backend

            - [x] Retrieval from frontend on PDF render

        - [x] User settings storage

        - [x] Onboarding

    - [x] Distribution 

        - [x] Electron-Forge implementation

        - [x] Downloadable

        - [x] Installable

        - [x] Updatable

        - [ ] Releases via GitHub

    - [x] Icon

    - [x] Formatting

    - [x] Code annotation & docstrings

    - [x] Documentation for early testers / contributers

    - [x] Public GitHub repository 

        - [x] Protected branches

        - [x] Pull request templates

        - [x] Issue templates

        - [x] Discussion boards

        - [x] Contribution guidelines & Code of Conduct

    - [x] Bug fixing: 

        - [x] Double execution of IPC calls

        - [x] Working input files for TeX compilation

        - [x] Off-center modals

        - [x] Reconfigure ESLint & TSDoc

        - [x] Fix useMediaQuery issue

2. Extra features & non-functional requirements (0.1.0 / beta release | 6%) 

    - [ ] Redesigned layout

    - [ ] Settings menu 

        - [ ] Rerender on settings change when necessary

        - [ ] Authentication token

        - [ ] Commit author identification

        - [ ] Auto-saving & updating settings

        - [ ] Resetting local storage

    - [ ] File operations 

        - [ ] Creation

        - [ ] Moving & renaming files

        - [ ] Lazy recursive folder expansion

        - [ ] Deletion

        - [ ] Merging

    - [ ] Editor 

        - [ ] Edit .bib files

        - [ ] Syntax highlighting

        - [ ] View non-editable files (e.g. images)

        - [ ] Temporary file viewing on single click

    - [ ] PDF rendering 

        - [ ] Use new rendering backend (Tectonic)

        - [ ] One-off TeX resource download

        - [ ] Selecting main file

        - [ ] Only overwrite changed files

        - [ ] Log with warnings and errors

    - [ ] Editor top-bar navigation between sections and subsections as in VSCode

    - [ ] Sections panel

    - [ ] Landing page

    - [ ] Overview of which files will be updated or merged before applying update

    - [ ] Onboarding tutorial

    - [ ] Test coverage 60%

    - [ ] CI/CD pipeline 

        - [ ] Integration tests

        - [x] Build

        - [x] Linting

        - [ ] Release

    - [ ] Auto-updates

    - [ ] Documentation (GH wiki using [typedoc-plugin-markdown](https://typedoc-plugin-markdown.org/docs))

    - [ ] Alpha release feedback processed

3. Polishing (1.0.0 / stable release | 0%) 

    - [ ] Beta release tested on a variety of systems

    - [ ] Project overview 'shelves' with previews

    - [ ] Auto-completion

    - [ ] Keyboard shortcuts

    - [ ] System features 

        - [ ] Dark Mode / Light Mode switching

        - [ ] Themes

        - [ ] Native look & feel

    - [ ] Test coverage 80%

    - [ ] Known issues have been processed

    - [ ] Availability on HomeBrew / App Store

4. Future

    - [ ] View of commit history with differences between files

    - [ ] Preloading of TeX files during installation

    - [ ] TeX Distribution selection

    - [ ] Import files from URL (Zotero)

    - [ ] Moving between editor and PDF location

    - [ ] Help pages

    - [ ] Browser extension support

    - [ ] Plugin support

    - [ ] Rich text editor

    - [ ] Multi-language support

    - [ ] Overleaf notifications



## Installation



Installation is as simple as [downloading the latest release](https://github.com/fjwillemsen/TurnALeaf/releases/latest) for Mac, Linux, and Windows. HomeBrew and App Store releases are planned (see [Roadmap](#roadmap)).

To use TurnALeaf with Overleaf, you need to have access to Overleaf's git integration (premium feature). If you don't have this, you can still use the app by for by hosting it on any Git platform (e.g. GitHub). Local file support is currently not planned, because Git is used to automatically backup your important work.

For building from source, see [Setting up the development environment](#setting-up-the-development-environment).



## Usage



TurnALeaf runs as a native web app, similar to Native Overleaf, but has a completely standalone editor and viewer built-in that functions as much like Overleaf as possible.

The Git integration built into Overleaf allows for seamless switching between TurnALeaf and Overleaf. 

Under the hood, TurnALeaf uses [SwiftLaTeX](https://github.com/SwiftLaTeX/SwiftLaTeX) to compile LaTeX to PDF locally and very fast thanks to WebAssembly. Note that an internet connection may still be required to download some files for compilation.

Edits are automatically saved to both your system and the remote server, meaning you won't have to worry about losing your work.



### Design Choices



For those interested, this project involved a lot of design decisions.

One of the most difficult choices was in picking between Electron and a more native approach, Tauri being the most popular.

On the one hand, the small bundle size, performance, self-updater and tight embedding in the OS provided by Tauri was very appealing.

On the other, Electron remains massively popular, well-documented and, most importantly, provides a consistent experience across platforms because of the bundled browser.

As this is one of the reasons the previous project [Native Overleaf](https://github.com/fjwillemsen/NativeOverleaf) was hard to maintain, Electron was chosen. Vite is used as a bundler (for hot-reload speed), React as the interface library, and PostCSS / Tailwind as the styling language (for convenience), based on a [electron-forge-react-vite boilerplate](https://github.com/flaviodelgrosso/electron-forge-react-vite-boilerplate).

[Mantine](https://mantine.dev/) is used as the UI component library.

To provide a standalone, Node-compatible git implementation, [isomorphic git](https://www.npmjs.com/package/isomorphic-git) is used.

Between [Electron-Forge](https://www.electronforge.io) and [Electron-Builder](https://www.electron.build), `electron-forge` is used, the reasons for which are well summarized [here](https://stackoverflow.com/a/43024627).



### Ideas, questions, contributions?



Please use the [GitHub discussions page](https://github.com/fjwillemsen/TurnALeaf/discussions) for this project. This allows others to read and chime in as well.

If you'd like to contribute, great! Feel free to submit pull requests via forks. Please note that pull requests on features in active development (see [Roadmap](#roadmap)) will likely not be accepted; to avoid duplicate work, first open an issue.

Be sure to check the [contributing guidelines](./CONTRIBUTING.md) for more practical information.