FR: Plugins should have links to help and code

Features
1

Hi

I think it will be beneficial if the plugin setting page has links to the help files and the github urls.

thanks

1 Like
2

Absolutely! And if plugins could have a short explanation that was visible from the plugin section itself that would be great too. A regular user shouldn't have to know to go to the forum and search for the plugin name.

1 Like
3

Click on the title of the plugin and the homepage of the plugin is opened in a browser.

2 Likes
4

Ah. I'm on 1.6.7, so maybe that feature isn't there.

I wouldn't have expected that behaviour anyway. Perhaps there should be one of those (i) dots next to the title. I think that is the standard way to indicate more information.

5

Yep, it's in 1.7.x - not sure which x, but the most recent pre-release has it.

The dots would make sense for more items. Currently there aren't any more options, thus not necessary.

2 Likes
6

Not quite sure what you mean by more items. What I meant was the circle with the letter i inside. Like this:
image

7

I believe @tessus was referring to these dots image (or the vertical version), which usually represent extra options. I thought the same :slight_smile:

1 Like
8

I see. I meant those 3 vertical dots that show up, when there are more options.

9

Haha, Caleb beat me to it. :wink:

2 Likes
10

Unfortunately it's not very consistent. I have seen plugin links that link to the devs homepage/blog, or to this forum, or to its github page.

2 Likes
11

Yes, this is true. But this is at the discretion of the dev. Some feel that a topic with replies and discussion is more useful than a gh repo. As long as the link provides some sort of documentation, it should be fine.

But I do have a few ideas for manifest.json version 2. I think I will create a separate topic for that.

12

I agree, there needs to be consistency. For something like this, it's important to remember that the end user (hopefully) won't always be someone who is tied in to the tech community. If you've never been to a github page before it is really, really confusing. Not sure what the alternative is, though.

Thanks everyone!

13

I'm sorry, but I have to disagree. You just scroll down and are presented with the README, which usually holds all the info wrt the repo/program/code/app.

14

I'm sorry, but I have to disagree with your disagree!! :grin:

I know to you it makes perfect sense. But I tell you, for people have never been to a git hub page before it is totally confusing. I'm not talking about a custom built github page. This is exactly what I see when I go to a plugin's github page:

image
image1891×762 98.7 KB

Has anyone who was an Evernote user ever been taken to a page like that to figure out how to use a feature? It's so easy when you are person on the inside to forget what it's like to be a person on the outside. I work with a lot of people who are regular computer users and I can tell you for sure, github pages are not a reasonable thing to send them to.

And it may also be surprising that most internet users have never posted to a forum before.

I'm not trying to be argumentative. I'm just trying to help you understand what it's like for someone who is not you. And I do appreciate all the hard work you have put in to Joplin.

15

I've never used Evernote and I seriously don't care. But if you scroll down just a little bit, you'll see the following (it can't be clearer than that, unless people can't read, but then they don't need Joplin in the first place):

Edit/Update: I don't want to be argumentative either, but scrolling a web page and reading can't be too much for a non technical person.

Joplin Persistent Editor Layout

Persistent Editor Layout is a plugin to extend the UX of Joplin's desktop application.

It allows to persist the editor layout for each note separately with special tags.

:warning: CAUTION - Requires Joplin v1.7.4 or newer

Table of contents

Features

  • Persist the editor layout (editor / split view / viewer / rich text) for each note separately
  • Using special tags
    • So persisted layout is synced across devices
    • Requires the plugin to be installed

Installation

Automatic (Joplin v1.6.4 and newer)

  • Open Joplin and navigate to Tools > Options > Plugins
  • Search for persistent editor layout and press install
  • Restart Joplin to enable the plugin

Manual

  • Download the latest released JPL package (*.jpl) from here
  • Open Joplin and navigate to Tools > Options > Plugins
  • Press Install plugin and select the previously downloaded jpl file
  • Confirm selection
  • Restart Joplin to enable the plugin

Uninstall

  • Open Joplin and navigate to Tools > Options > Plugins
  • Search for the Persistent Editor Layout plugin
  • Press Delete to remove the plugin completely
    • Alternatively you can also disable the plugin by clicking on the toggle button
  • Restart Joplin

Usage

Persist layout for a note

To persist the layout for a note simply add one of the following tags as specified:

Tag Layout
layout:editor Markdown: editor view
layout:split Markdown: Split view
layout:viewer Markdown: Rendered view
layout:richtext Rich text (WYSIWYG) editor

This can be done by manually adding them to the notes or via the command.

  • The setting View > Layout button sequence must be set according to the tags used.
    That means, if the tag layout:viewer is set in at least one note, the setting must also contain Viewer.
    Otherwise layout will not be changed to the expected one.
  • When the selected note is changed, the editor layout is changed also.
  • If none of the tags is specified, the default layout from user option Default editor layout will be used.
    • If None is selected, the currently active layout will be kept.
  • If more than one is specified, they are checked in the order above and the first matching one is used.

Commands

This plugin provides additional commands as described in the following table.

Command Label Command ID Description Menu contexts
Persist editor layout persistEditorLayout Persist the current active editor layout for the selected note(s) Tools, NoteListContext, Command palette

Keyboard shortcuts

Keyboard shortcuts can be assigned in user options via Tools > Options > Keyboard Shortcuts to all commands which are assigned to the Tools menu context.
In the keyboard shortcut editor, search for the command label where shortcuts shall be added.

User options

This plugin adds provides user options which can be changed via Tools > Options > Persistent Layout.

Feedback

  • :question: Need help?
  • :bulb: An idea to improve or enhance the plugin?
  • :bug: Found a bug?
    • Check the Forum if anyone else already reported the same issue. Otherwise report it by yourself.

Support

You like this plugin as much as I do and it improves your daily work with Joplin?

Then I would be very happy if you buy me a beer via PayPal :wink::beer:

Development

The npm package of the plugin can be found here.

Building the plugin

If you want to build the plugin by your own simply run npm run dist.

Updating the plugin framework

To update the plugin framework, run npm run update.

Changes

See CHANGELOG for details.

License

Copyright (c) 2021 Benjamin Seifert

MIT License. See LICENSE for more information.

1 Like
16

I think the issue is that plugin developers link to their repo directly while they should directly link to their README. But in any case there can't be consistency since each developer is free to link to anything they consider useful as a "homepage", so indeed even a forum post can be the right place.

The alternative would be to host ourself the plugin documentation, like DockerHub is doing for example, but I'd rather not go there at this point.

1 Like
17

I have most of my experience with WordPress and their repository. For WP, each plugin is required to have a read me file that adheres to strict structure. That's actually what we are looking at when we go to the WP repository or when we are within our own admin area and click on more details on a plugin. Once the plugin is installed on you site, you can click a link that says "details" and that's what pops up (never leaving your own admin area).

Personally I really like this method. There is some uniformity. And developers are welcome to link to wherever they like within that readme. They can even link to both the github and the forum thread.

Here is what the plugin list looks like (in part)

image
image1279×706 51.3 KB

Then when you click on View Details, you get this:

image
image1472×858 85.3 KB

The tabs and the info on the side bar are all pulled from the readme file.
README.txt (3.4 KB)
It ends with txt but I believe it's actually markdown.

Someone has actually created a webapp to help you create the file and ensure it fits the standard:

It might be better to standardize this sooner rather than later.

I think in the long run, this isn't the best thing for end users. I use another platform that has taken this approach and I don't find it nearly as user friendly as WP.

Just some thoughts. Thanks for all the development work!

1 Like
18

We could also try to find out in the Joplin code, whether a README.md exists at the repo_url and/or homepage_url address. If so, just go to that page instead.
I agree, it will add more code that has to be maintained, but short of forcing plugins devs to link to a README, there's no better solution.

Hosting documentation can be a maintenance burden.

1 Like
19

I don't think it's a good idea to do too complicated things here. I prefer to rely on whatever URL the plugin developer gives and let's see if over time it's really a problem.

20

I do not think that Joplin should enforce anything or spend serious development time, but giving some guidance to plugin developers cannot hurt, either. Also I fully agree with @whitewall concerning how easy a github-page is to navigate for non-devs.

Suggestion

The current manifest already has two fields for homepage_url and repository_url. Currently, most examples simply fill both with the same github-url (see here and here).

Let's try to lead the devs towards filing the first field with a link to documentation, e.g. by

  • adding a better description to the yeoman questionnaire (replace homepage prompt by documentation, e.g. URL of README.md)
  • updating the examples so their homepage_url points to a README.md
  • pre-filling manifest-fields, if there are "empty" example manifests somewhere
		"homepage_url": "[insert link to your documentation here, e.g. link to a website or direct link to README.md in your repository]",
		"repository_url": "[insert link to the plugin repository here]",

Additionally, one might come up with a common README.md structure as recommendation for plugin authors.

On a related note, the link to the example manifest.json (last sentence in Getting started with plugin development | Joplin) is currently broken and should probably point here @laurent

2 Likes