toolstack / folio

A beautiful markdown note-taking app for GNOME (forked from Paper)

Folio

Take notes in markdown

A beautiful markdown note-taking app for GNOME (forked from Paper).

Contributions are appreciated, see below for how to help translate Folio!

Some of Folio's features are:

• Almost WYSIWYG markdown rendering
• Searchable through GNOME search
• Highlight and strike-through text formatting
• Application theming based on notebook color
• Trash can
• Markdown document
• Optional line numbers
• Optional auto save
• Open links with Control-Click
• Link to other notes in Folio
• Automatically create links for bare URL's and e-mail addresses

Get Folio

The recommended way of installing Folio is through Flatpak or Snap or as an AppImage:

From Flathub

From Snapcraft

AppImage

Manually

Go to the current GitHub Releases page, select the latest release, and download the asset called Folio-YY.##.flatpak. Once downloaded, use flatpak install Folio-YY.##.flatpak to install Folio on your computer.

You can use the same process to update to a newer release as well.

Libraries Used

• libadwaita
• gtksourceview-5

License

The source code is GPLv3

Notes Storage

By default, notes are stored in ~/.var/app/com.toolstack.Folio/data, but that can be changed in preferences

Translations

Folio has been translated into several different languages by users. Previously this was done by submitting pull requests to add the various language files.

Folio now has an online localization portal, if you would like to participate in translating Folio, send an e-mail and request access for the language you would like to translate.

Build Instructions

Flatpak build requires flatpak-building installed.

Local builds (NOT RECOMMENDED)

• change into the top level source directory
• to configure the build environment (required only once), run meson build
• change into the build directory
• to build Folio, run ninja
• to install Folio, run ninja install
• to run Folio, run src/com.toolstack.Folio

Flatpak builds

• install flatpak-builder if not already installed
• change into the top level source directory
• to build the flatpak, run flatpak-builder --force-clean flatpak com.toolstack.Folio.json
• to build and install the flatpak, run flatpak-builder --user --install --force-clean flatpak com.toolstack.Folio.json
• to launch the flatpak, run flatpak run com.toolstack.Folio

Snap builds

• Install snapcraft if not already installed
• change into the top level source directory
• to build the snap, run snapcraft
• to install locally, run sudo snap install ./folio_YY.XX_amd64.snap --dangerous
• to launch the snap, run folio

AppImage builds

• Install linuxdeploy if not already installed
• change into the top level source directory
• create the directory AppImage (if it already exists, ensure to remove all of its contents)
• change into the build directory
• set the DESTDIR environment variable as follows: export DESTDIR=../AppImage
• run build/install with ninja install
• change to the AppImage directory
• use linuxdeploy to build the AppImage: linuxdeploy --appdir=. -d usr/local/share/applications/com.toolstack.Folio.desktop -i usr/local/share/icons/hicolor/scalable/apps/com.toolstack.Folio.svg -e usr/local/bin/com.toolstack.Folio --output appimage
• to launch the AppImage, run Folio-x86_64.AppImage

Release instructions

Folio uses a YY.## version format string, where YY is the two digit year (aka 23, 24, 25, etc) and ## is the release number of the year (aka 01 for the first release, 02 for the second release, etc., not the month number).

The release version is located in the main meson.build file, no other files contain the version number.

The full changelog is located in data/app.metainfo.xml.in and the current release for the about dialog is in src/application.vala.

Before doing a release, make sure to e-mail the translation editors to let them know to update the translations. This should be done at least 2 days in advance to give them time to make their updates. Once they update are done, make sure to export the translations and commit them to git.

Once updated, edit the flatpak and snap files:

• change into the top level source directory
• edit com.toolstack.Folio.json and update the tag value for sources, also remove the commit hash (don't forget to remove the comma on the line above) temporarily (we'll add it back later)
• change into the snap directory
• edit snapcraft.yaml and update the source-tag

Commit everything to git.

Now go to github and do the release.

After the release is done get the hash value for the commit for the new release tag and then add back the commit line in com.toolstack.Folio.json. Commit it back to git as well.

Two actions should have been kicked off on the github release, one to build the flatpak and the other to build the snap. These will take a few minutes to complete, but once they do, go to each one and download the built assets.

You will need to build the AppImage manually, follow the instructions above on how to do that and retrieve the generated Folio-x86_64.AppImage file.

Extract both zips that you downloaded and rename the resulting flatpak/snap/AppImage to "Folio-YY.XX[-platform].[flatpak/snap/AppImage]".

Go back to the release and attach these files to the release assets.

Now do the releases on Flathub and Snapcraft.

Flathub release

• get a clone of the flathub repo: https://github.com/flathub/com.toolstack.Folio.git
• create a new branch labeled "YY.XX"
• switch to the new branch
• edit com.toolstack.Folio.json and update both the tag and commit lines to reflect the new release
• commit the changes
• go to github and create a new PR to merge the branch into master
• commit the PR
• monitor the buildbot

Snap release

• after build, login to your snapcraft account snapcraft login
• upload the build snapcraft upload --release=stable folio_YY.##_amd64.snap

Generate translation POT

Folio uses POT/PO files for it's translations, the POT file defines all the strings that are used by Folio.

Before generating the POT file you must have already run meson for the first time and have run a local build.

To generate the POT file:

• change into the PO directory
• run ./generate-POT-file.sh

FAQ

How to link to other notes

Folio supports linking to other notes via the standard markdown link syntax, with the url being a relative path to another note. For example, if you want to link to a note called "My big list of links" in the same notebook, then any of the following will work:

• [my link](file://./My big list of links)
• [my link](./My big list of links)
• [my link](./My big list of links.md)

If you want to link to another notebook called "Junk links", you can use any of the following formats:

• [my link](file://../Junk links/My big list of links)
• [my link](../Junk links/My big list of links)
• [my link](../Junk links/My big list of links.md)

Integrating with Nextcloud Notes

Nextcloud notes uses markdown files to store it's information in and has an API to access these, however Folio does not support the API, but can still integrate with Nextcloud notes.

You have two options, either connect with WebDav and expose the notes directory as a filesystem or use the Nextcloud desktop client to synchronize the notes directory to your desktop.

In either case you can then go into Folio's preferences and change the storage location to the Nextcloud Notes folder. You might want to unhide the trash folder, otherwise you'll see a ".trash" folder in your Nextcloud Notes on other clients (unhiding renames it to "Trash").

You may also want to change the trash folder's location to somewhere else on the file system to avoid synchronizing it back to Nextcloud.

There are a few cavitates when using Folio with Nextcloud notes:

• Folio will monitor the currently displayed note for any changes on the filesystem and reload it automatically if no changes have been made in Folio. If a change has been made, Folio will prompt you to either reload the note or overwrite it.
• Folio will also check if a note has been changed when you save it, once more prompting for what to do if it sees a change on the file system that Folio did not make itself.
• Folio will not monitor for new notes or notebooks at this time, issue #58 is open to address this at some point in the future.
• Folio only supports a single level of notebooks, so any Nextcloud notes that are store more than one level deep (aka in subfolders of subfolders) will not be displayed in Folio. Issue #11 is open to address this at some point in the future.

Why fork Paper?

Unfortunately Paper is out of date and the developer does not have the time/interest to maintain it any more.

Ok, so what is Folio's main focus

The primary focus of my fork is getting everything up to date and supported for the long term.

A secondary focus is feature additions. Some new features that have already been added are:

• Better handling of escaped characters in code spans.
• Reworking of the format bar to act more like use user expect, including toggling formatting and smarter formatting.
• Control-click to open links in a browser.
• Marking non-markdown formatted links and email addresses.
• Fixed a ton of crashes caused by files without ending EOL markers.
• Automatically insert formatting around current words instead of in the middle of them.

You can see what's planned via the issue tracker at GitHub.

So what isn't planned

Folio is not a replacement for applications like OneNote or other advanced note taking apps, as such, there are some features that will never be added to Folio, like:

• Image markup
• Handwriting support
• MathML
• PDF or other document type embedding

Basically anything that tries to make Folio into something other than a markdown editor.

Of course if someone created a PR that added one or more of those things, I'd be open to reviewing it and see if the implementation fits well or not.

Using Folio with cloud storage providers

You can use Folio with cloud storage providers like Google Drive, however there are a few things to keep in mind:

• Cloud services are slower than local storage, large notebook/note collections may be slow to load on startup.
• Detection of changes to notes may be impacted, as cloud providers may not indicate a file change on the server in a way that Folio will detect.

Google Drive Integration with GNOME

• Google Drive's integration in GNOME does not use display names on disk, but instead file hashes, so when selecting the notes folder you will see the display names, but after selecting the folder the hash values will be displayed in the file location box on the preferences screen. Display names will be used in the notebook and notes list.
• Performance may be impacted as the display names must be retrieved from the cloud, which is of course slow in comparison to local file names.

Nextcloud Integration with GNOME

• GNOME's integration with Nextcloud is effectively a WebDAV connection so all data is keep in the cloud. This may impact performance.

Non GNOME Integrated Cloud Providers

Cloud providers that do not integrate directly with GNOME or have alternatives to GNOME's integration (like Nextcloud) should work and may not have the above mentioned issues.

In general, if your cloud provider has a sync client, that copies your data to your local disk and keeps it up to date, you will have a better experience with Folio than a client that tries to use the cloud directly.

folio's Issues

Core dumped Error while run Appimage

When I open Folio.appimage, the below error occurred:

(com.toolstack.Folio:577910): GLib-GIO-ERROR **: 16:39:29.438: Settings schema 'com.toolstack.Folio.Theme' is not installed
[1]    577910 trace trap (core dumped)  ./Folio

Folio: Version 24.10
Os: ubuntu 23.10

"All notes" only appears when Search is active

It would be great to always be able to see a list of all your notes, even if Search is not active.

Implement autosave

What the title says. It would be very useful to have notes saved automatically after a change happens.

feature request: double click note title to rename

Allow for smaller minimum width

Notes' width doesn't seem to adjust to the window:

Is this a bug?

Support for Nextcloud Notes

Support for Nextcloud Notes would be great. Is this within the scope of this project, or do you plan to keep Folio a local only Markdown Notes editor?

Why?

• There are already many Nextcloud users in the Linux community
• It would enable you to write notes when on your non Linux phone
• It would enable you to sync your notes on your Linux phone and Desktop
• Users can write notes on the go, reducing the risk to forget ideas (or what ever they want to note down)

How?
Nextcloud Notes has a simple API, which is documented here.

There is already another Adwaita App that uses the Nextcloud Notes API. But its markdown capabilities are a bit limited.

https://gitlab.gnome.org/cheywood/iotas/-/tree/main/iotas

Subfolders

Would it be possible to get a function to create subfolders?

Create new notes and link to them automatically

I used to use a note-taking app called Tomboy, which had this really, really useful feature:

While you were inside a note, you could select text (e.g. select the words "shopping list" and click a specific button; then, a new note called "shopping list" would be created; and every time you wrote the words "shopping list" in any other note, they would link to that note.

Again: it was extremely useful.

Is there any chance that Folio could have this feature?

Snap package

Hi, I previously created a snap for the paper, and have a snap for this app also. Would you like to have it as official?

Alpha sort for notebooks is wrong way round 24.09

Setting Ascending for Notebooks reverse sorts it.

May I suggest you consider naming these "Alphabetical" and "Reverse Alphabetical"? I have to think which way is "Ascending". In any case, the Notebooks and Notes sort the opposite way to each other, as above.

Moreover, I cannot actually think of a use case for "Reverse Alpha" as a setting?

Support ordered/unordered lists

Order/unordered lists are not currently supported, while we can't replace unordered list with "real" bullets due to limitations in the sourceview widget, we can still format with an indent them properly.

Motivation of the fork

Hello, I just saw the Flathub release and checked if Paper was still in development. And it is. So I am wondering what the motivation for forking was. What advantages does Folio hope to provide to its users? Usually, forks provide this information in their readme (or similar) to attract user and contributors.

Thank you.

Feature request - re-order notes?

You may well have this on your list of things to do...

But when adding notes, they appear to be sorted in the order of creation, with no way to re-order them (i.e. move one to the top etc.). Although I do notice that dragging seems to be enabled, but doesn't actually do anything.

Would be nice to re-order them in some future version if you would consider?

Add option to disable trashcan

The trashcan is a nice safety net, but some users might not want it, so create an option to disable it directly delete notes when told to.

[Enhancement] Attach, Display Images, Files

My workflow involves mostly text notes I can make in Markdown, but there are some notes that require handwriting. I use an ipad app that exports SVGs.

Being able to embed displayable files (images, vector graphics, maybe even PDFs?) would be great.

I also would like some way to control/default width so that the handwritten text is at a decent scale. My notes expand downwards, so the final image/vector is extremely tall, but the width should match roughly the width of a paragraph text.

Markdown seems to be broken 24.06

Issues in markdown. Below

Support double backticks for code spans

Double backticks are used to allow for use of single backticks inside of the span.

Folio currently does not support his case, so it should be added.

Ability to set mounted Google Drive as the save folder

Currently when I try to set the note saving folder as one of my folders in Google Drive (that I set-up using Gnome's native Online Accounts feature) it fails to recognize it as a valid folder path. It'd be amazing and game-changer to have it to be able to sync/save files directly to google drive making it accessible from various devices!

Feature request: Adding Support for Tables in Notebook Notes

Description:

As a user of Folio, I've been utilizing the notebook feature extensively for organizing my thoughts, documenting processes, and keeping track of important information. However, I noticed a missing piece that would greatly enhance the usability and versatility of this feature: the ability to create tables within the notes.

Proposal:

I'd like to suggest adding support for creating tables directly within the notebook notes. This would enable users like me to present structured data in a clear and organized manner, right alongside our text content. Here's how it could work:

1. Simple Table Creation: Introduce an intuitive way for users to define tables within the markdown-based notebook notes. This could involve a syntax similar to what's used in other markdown environments, making it easy to learn and use.

2. Visual Table Editor: Implement an interactive interface within the notebook editor, allowing users to create and edit tables visually. This would include options for adding/removing rows and columns, adjusting cell contents, and customizing the appearance of the table.

3. Basic Table Operations: Ensure that essential table operations such as sorting, filtering, and resizing are supported, making the tables more functional and user-friendly.

Benefits:

• Improved Organization: With the ability to include tables, users can better structure and present their data within the notebook, enhancing readability and comprehension.

• Enhanced Collaboration: Teams collaborating on projects can benefit from sharing structured data within the notebook, facilitating better communication and understanding.

• Increased Versatility: Adding support for tables expands the range of use cases for the notebook feature, making it a more versatile tool for project management, documentation, and data analysis.

Implementation Details:

• Consider leveraging existing libraries or frameworks for rendering and manipulating tables within the notebook environment, ensuring compatibility with different markdown parsers and editors.

• Gathering feedback from users on their specific needs and preferences regarding table functionality can help prioritize key features and ensure a user-friendly implementation.

Additional Notes:

As someone who relies on the notebook feature for various tasks, I believe that adding support for tables would significantly enhance its usefulness and make Folio an even more valuable tool for users.
I'm eager to see this feature implemented and would be happy to provide further feedback or assistance in any way possible.

Thank you for considering this suggestion. I'm excited about the potential for improving the notebook feature, and I'm confident that adding support for tables would be a valuable addition for users like me.

Feel free to adjust any details to better fit your specific situation!

Not possible to change the icon of a notebook

It does not seem possible to update the icon in a notebook -- Apply stays grayed out.

See screenshot.

Create AppImage

As the title says.

Syntax highlighting

Currently, the best tool for keeping this type of notes is Obsidian, but it is not licensed under OpenSource. Folio may be an interesting replacement for Obsidian, but it still lacks a lot of functionality.

• First, Syntax highlighting.
• Automatic closing of blocks such as ``` or `
• Access to the data directory via WebDav

Good job

Too much tall shape around the menu button

Just noticed the shape around the menu button is a bit too tall, it should keep a normal margin on top and below 😉

Screenshot :

Suggestion - Unit tests?

This is merely a suggestion. Let me say this that is your project, which I use, and am grateful for. And I realise that it's up to you how you manage it and what features you put in etc. That being said...

I'm not familiar with vala but I don't see any unit tests in the source. You'd not only catch many bugs, but catch most regression issues. Something to consider?

Feature Request: Click (or copy) link from notes

Adding a link using []() is great. However, it is not (seemingly) possible simply click on the link and have in open a browser. Moving the cursor over the link leaves it at the insert cursor, and pressing CTRL does nothing.

In fact, using []() makes it harder to get the link into a browser because you have to manually select the text, and when you do so, that shifts the link into edit mode.

Is it possible that, when you hold down CTRL, moving the cursor over a link shows the point cursor and clicking opens a browser?

If not possible, is it possible to simply put a copy button next the link when not editing it?

Thank you

PS. Folio/Paper is both simple and brilliant.

Move a note to a different notebook

Could there be an option to take an existing note and adding it to a different notebook? Thanks!

Implement printing notes

An elder relative recently told me she needed a way to create and print notes. Assuming a word processor would be too complex for her, I decided to install Folio on her computer. But sadly, she can't use it to print her notes.

Would it be possible to implement printing notes, so that this person can use Folio and I don't need to direct her to a more complex app?

Thanks in advance.

Broken 24.07

Now doesn't show anything.

See Folio vs Paper.

Sorry.

Feature Req - Find?

Hey,

I understand Folio is linked in to desktop search.

But there doesn't appear to be a way to "Find" within a single page.

How about a simple "Find" (in page) option that responds to F2? Perhaps with case and whole word option, like VSCode.

Sort by most recent change

Notes are currently sorted by creation date, which is not very useful when a note is very old but also very frequently used. There should be an option to have the most recently used notes at the top of the list.

Reset scroll position when switching between notes

Scroll position is left at the current location when switching notes instead of being reset to the start.

Monitor the notes directory for new/deleted notes and notebooks.

Folio needs a restart to see notes/notebooks that are created on disk outside of Folio. Let's create a monitor for changes in the notes directory and make the change as required inside Folio.

Issue with adding notebooks with duplicate names

Hi,

First of all, I would like to thank you for reviving the old Paper project. It is a great resource for the community and I appreciate your efforts in bringing it back to life.

I am writing to report an issue I encountered while using the app. When I try to add a new notebook with the same name as an existing notebook, nothing happens. The notebook is not added and the application does not provide any feedback indicating that there is a duplicate name.
I think displaying an error message next to the name, indicating that the notebook name is already in use, would be immensely helpful.

Replace Regex based markdown parser

There's just stuff that's not doable through Regex, Folio needs a proper state machine based parser.

There should be one out there somewhere that can be used so Folio doesn't have to create one. Perhaps the CommonMark library or something similar.

Folio crashes when trying to find a renamed folder

Folio crashes when renaming through an external tool (i.e. , a file manager).
Steps to reproduce :

• Open Folio
• Choose a folder to be on (doesn't matter which one)
• Rename through an external tool a folder (doesn't matter which one)
• Click on the renamed folder and click back (also works if you are already on the renamed folder).
• Folio crashes and produces the following output :

`(com.toolstack.Folio:2): GtkSourceView-WARNING **: 19:49:15.650: in file /app/share/gtksourceview-5/language-specs/markdownpp.lang: style 'def:text' not defined

(com.toolstack.Folio:2): Gtk-WARNING **: 19:49:15.982: GtkBox 0x5f62c4380500 (box) reported min width -3, but sizes must be >= 0

(com.toolstack.Folio:2): Gtk-WARNING **: 19:49:18.919: GtkBox 0x5f62c4768940 (box) reported min width -3, but sizes must be >= 0

** (com.toolstack.Folio:2): ERROR **: 19:49:35.019: file_utils.vala:24: Erreur lors de l’ouverture du fichier « /home/basilek/Documents/Markdown/Oral stage BUT-S2/Première partie.md » : No such file or directory`

Support for checkboxes

Markdown supports checkboxes and Folio should be able to show a simple checkbox when [] is typed.

Appdata screenshot papercuts

There are a few minor issues with the current appdata screenshots:

• Window is not focused (see unfocused headerbar items)
• Window size larger than 1000x700px (I'm pretty sure, though didn't check)
• Non-standard window controls (should be close-only)

Flathub guidelines: https://docs.flathub.org/docs/for-app-authors/appdata-guidelines/quality-guidelines/

Implement Search only in current file.

Allow to create single ASCII files (.txt)

It could be nice to allow creating single ASCII when adding a new file.

Spellcheck

This might be out of scope. If it is feasible to include, I would suggest it does not appear at all in the app's interface unless enabled in preferences, and if it is enabled, it should be inactive unless toggled for a specific page or notebook.

Update notes list after saving a note

Currently the notes list is sorted by last update, however when you save a note the list isn't update to reflect the recently saved note.

Inform translators before new releases

Good to see the Paper project having a new life under the name of Folio.

Please inform the translators about the fork and your project before new releases. They would probably be happy to update the translations.

Thanks.

Can't Create Note - 22.05 - actually it's a flatpak permission issue

I updated to the lastest flatpak using Gnome explorer. To do this, I first removed the previous version, which I had installed as a flatpak file download via the command line.

Now, can't now create new notes. Screenshot attached.

As I write this, I discovered the problem -- Folio needs the Flatpak permission to access the note storage location.

You see, I have multiple drives mounted under /mnt, and I can't be the only one with multiple drives where much of my stuff is not stored under home. For me, most flatpaks apps are unusable without Flatseal. :(

Anyway, see screenies. And thanks for the updated version. It's working now I have changed the permission in Flatseal. But something you want to consider in next version?

Add Support For Auto-Bulleting/Numbering

Title is self-explanatory. I would reference Apostrophe (the development builds are for GTK4/Libadw) or Zim (though Apostrophe is much closer to what you're attempting) for the implementation. Keyboard shortcuts/buttons would also be appreciated (at least for unordered/bullet).

an empty trash displays a "new note" button

empty trash shows "Start writing [New note]"

the button is grey but clickable but doesn't create anything, it tells me to select a notebook first.

original paper displays "Trash is empty" here

URL detection is too aggressive

From what I can see, Folio auto detects a link in the text if merely contains a . with no whitespace. As a result, it also characterises simple file names and namespaces as links and my notes are littered with false positive "links".

See screenie.

May I suggest for purposes of auto-link detection, a text fragment must contain (but not start or end with) both:

://, .

where the first occurrence of . must be after the :// the scheme separator.

Or as well: a fragment may start with www. instead of containing ::/, though few use www any more.

This obviously shouldn't apply to links explicitly designated with ()[].

Add Markdown Preview

This is not essential because it's already semi-WYSIWYG, but a pure preview view-only mode, maybe with a dropdown for different Markdown formats, would be appreciated.

image syntax from the cheatsheet doesn't work

in the built-in cheat sheet you can see this:

![Image alt text](https://imageurl.io)

but it doesn't actually work in notes, it's just a "!" and a link

Scroll Bar for Notes

Hey,
There does not seem to be a scroll bar for notes. The arrow keys seem to work to move around notes.
A scroll bar would be nice too.
Screencast from 2024-03-05 15-35-30.webm

Add line number display option

The sourceview widget can display line numbers for the file, so let's add an option (disabled by default) to display them.