rooty/Mstdn
1
0
Fork 0
mirror of https://github.com/rhysd/Mstdn.git synced 2025-02-27 05:54:15 +01:00
Code Issues Releases Activity

README updates (#26)

Browse Source 
* README updates

* added AUR link

* Update from PR
This commit is contained in:
Sumner Evans 2017-05-28 21:00:18 -06:00 committed by Linda_pp
parent 262e839e25
commit 10754d1305
1 changed files with 146 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
README.md
View File

@ -2,9 +2,10 @@ Web-based Desktop Client for [Mastodon][]
========================================= =========================================
[![npm version][npm version badge]][npm] [![npm version][npm version badge]][npm]
Mstdn is a desktop application based on mobile version Mastodon page and [Electron][] framework. Mstdn is a desktop application based on the mobile version of the Mastodon page
It basically uses Mastodon's mobile page and provides various desktop application features and the [Electron][] framework. It basically uses Mastodon's mobile page and
(such as desktop notification, keybinds, multi-account support). provides various desktop application features (such as desktop notifications,
keybindings, and multi-account support).
<img src="https://github.com/rhysd/ss/blob/master/Mstdn/main.png?raw=true" width="484" alt="screen shot"/> <img src="https://github.com/rhysd/ss/blob/master/Mstdn/main.png?raw=true" width="484" alt="screen shot"/>
@ -17,11 +18,13 @@ Features:
- [x] User CSS - [x] User CSS
- [x] Plugin architecture based on Node.js and Electron APIs - [x] Plugin architecture based on Node.js and Electron APIs
Mastodon is an open source project. So if you want to make a new UI, you can just fork the project, Mastodon is an open source project. So if you want to make a new UI, you can
implement your favorite UI and host it on your place. Then you can participate Mastodon networks from it. just fork the project, implement your favorite UI and host it on your place.
Then you can participate Mastodon networks from it.
However, Mastodon is a web application. So we can't go out from a browser. This small tool provides However, Mastodon is a web application. So we can't use it outside of a browser.
the ability to Mastodon page in desktop application window out of browser. This small tool provides the ability to use the Mastodon page in a desktop
application window outside of a browser.
## Installation ## Installation
@ -39,44 +42,57 @@ $ yarn global add mstdn --prefix /usr/local
### As an isolated app ### As an isolated app
Download a package archive from [Release page][], put unarchived app to proper place, and open it. Download a package archive from the [Release page][], put the unarchived app
into the proper place, and open it.
### Arch Linux ([AUR][])
Install the `mstdn` package from the AUR.
## Usage ## Usage
If you installed this app via npm or yarn, below command is available to start app. If you installed this app via npm or yarn, the following command is available to
start app:
``` ```
$ open-mstdn-app $ open-mstdn-app
``` ```
At first, a dialog which recommends to write up config is shown and JSON config file will be open in your editor. At first, a dialog which recommends that you create a config is shown and JSON
You need to fill up `"name"` and `"host"` keys in first element of `"accounts"`. Please see below `accounts` section config file will be opened in your editor. You need to fill in the `"name"` and
to know how to configure the option. `"host"` keys in first element of `"accounts"`. Please see the `accounts`
section below for more information about how to configure the option.
Then please try to start app again. Usage is the same as web client on mobile devices. Then please try to start app again. Usage is the same as web client on mobile
Some shortcuts are available by default (please see below 'Customization' section). devices. Some shortcuts are available by default (please see the 'Customization'
section below).
Supported platforms are macOS (confirmed with 10.12), Linux (hopefully) and Windows (confirmed with Windows 8.1). Supported platforms are macOS (confirmed with 10.12), Linux (confirmed on Arch
Linux kernel version 4.11) and Windows (confirmed with Windows 8.1).
There are two window modes 'menubar mode' and 'normal window mode' in this app. You can switch There are two window modes in this app: 'menubar mode' and 'normal window mode'.
them with `"normal_window"` option (please see below 'Customization' section for how to configure it). You can switch them with `"normal_window"` option (please see below
'Customization' section for how to configure it).
- **menubar mode**: Window is attached to menubar. You can toggle the window by clicking menubar icon or typing hot key. - **menubar mode**: Window is attached to the menubar. You can toggle the window
Advantage of this mode is that app does not fill any workspace. You can see your timeline on demand anytime. by clicking the menubar icon or typing the hot key. The advantage of this mode
This mode is default on macOS or Linux. is that the app does not fill any workspaces. You can see your timeline on
- **normal window mode**: App starts with a normal window like a separated browser window. You can put/resize window demand anytime. This mode is the default on macOS and Linux.
as you like in your workspace. - **normal window mode**: App starts with a normal window like a separated
browser window. You can put/resize window wherever you would like in your
workspace.
In both modes, app remembers the size and location of its window. So you need to specify window size In both modes, the app remembers the size and location of its window. So you
(or location in normal window mode) only once. need to specify window size (or location in normal window mode) only once.
After starting app, you would see login page of your instance. Some instances allow to login with After starting the app, you would see the login page of your instance. Some
other web services. However, Mstdn.app cannot fully support it. If you encounter some problem instances allow to login with other web services. However, Mstdn.app cannot
with customized login feature, please try to login with normal flow instead. fully support it. If you encounter problems with a customized login feature,
please try to login with normal flow instead.
## Customization ## Customization
Mstdn can be customized with JSON config file at `{app dir}/config.json` Mstdn can be customized using the JSON config file at `{app dir}/config.json`
The `{app dir}` is: The `{app dir}` is:
@ -84,29 +100,32 @@ The `{app dir}` is:
- `~/.config/Mstdn` for Linux - `~/.config/Mstdn` for Linux
- `%APPDATA%\Mstdn` for Windows. - `%APPDATA%\Mstdn` for Windows.
The JSON file can contain below key-values: The JSON file can contain the following key-values:
### `hot_key` ### `hot_key`
`hot_key` is a key sequence to toggle application window. The shortcut key is defined globally. `hot_key` is a key sequence to toggle application window. The shortcut key is
The format is a [Electron's accelerator](https://github.com/electron/electron/blob/master/docs/api/accelerator.md). defined globally. The format is an [Electron's
Please see the document to know how to configure this value. accelerator](https://github.com/electron/electron/blob/master/docs/api/accelerator.md).
Default value is `"CmdOrCtrl+Shift+Enter"`. If you want to disable, please set empty string or `null`. Please see the document to know how to configure this value. Default value is
`"CmdOrCtrl+Shift+Enter"`. If you want to disable, please set this value to an
empty string or `null`.
### `icon_color` ### `icon_color`
Color of icon in menubar. `"black"` or `"white"` can be specified. The color of icon in menubar. `"black"` or `"white"` can be specified.
### `always_on_top` ### `always_on_top`
When this value is set to `true`, the window won't be hidden if it loses a focus. Default value is `false`. When this value is set to `true`, the window won't be hidden if it loses a
focus. Default value is `false`.
### `normal_window` ### `normal_window`
When this value is set to `true`, application will be launched as a normal window application. When this value is set to `true`, application will be launched as a normal
If menu bar behavior does not work for you, please use set this value to `true` to avoid it. window application. If the menu bar behavior does not work for you, please set
Default value is `false` on macOS or Linux, `true` on Windows because window position is broken this value to `true` to avoid it. Default value is `false` on macOS or Linux,
in some version of Windows. `true` on Windows because window position is broken in some versions of Windows.
### `hide_menu` ### `hide_menu`
@ -118,35 +137,42 @@ On Windows, typing Alt key shows the hidden menubar.
### `zoom_factor` ### `zoom_factor`
Font zoom factor in application. It should be positive number. For example, `0.7` means `70%` font zooming. Font zoom factor in application. It should be positive number. For example,
Default font size is a bit bigger because the UI is originally for mobile devices. So default value is `0.9`. `0.7` means `70%` font zooming. Default font size is a bit bigger because the UI
is originally for mobile devices. So default value is `0.9`.
### `accounts` ### `accounts`
Array of your accounts. An element should has `"name"`, `"host"` and `"default_page"` keys. Array of your accounts. Each element should have `"name"`, `"host"` and
`"default_page"` keys.
`"name"` represents your screen name. If your name is `@foo` then please specify `"foo"` for it. - `"name"` represents your screen name. If your name is `@foo` then please
specify `"foo"` for it.
`"host"` represents a host part of URL of your mastodon instance. If you belong to - `"host"` represents a host part of URL of your mastodon instance. If you
`https://mastodon.social`, please specify `mastodon.social`. `https://` is not necessary. belong to `https://mastodon.social`, please specify `mastodon.social`.
`https://` is not necessary.
`"default_page"` is a path of page firstly shown. If `/web/notifications` is specified, - `"default_page"` is a path of the first shown page on app start. If
`https://{your host}/web/notifications` will be open on app starting. `/web/notifications` is specified, `https://{your host}/web/notifications`
will be opened when the app starts.
You need to write up this config at first. You need to write up this config at first.
### `chromium_sandbox` ### `chromium_sandbox`
If `true` is specified, Chromium's native sandbox is enabled (and default value is `true`). If `true` is specified, Chromium's native sandbox is enabled (and default value
Sandbox provides some OS level security protection such as resource access control like tabs is `true`). Sandbox provides some OS level security protection such as resource
in Chromium. However, sandbox also blocks plugins for Electron application. access control like tabs in Chromium. However, sandbox also blocks plugins for
Electron application.
If `false` is specified, you can use some advanced features (user CSS and key shortcut plugin). If `false` is specified, you can use some advanced features (user CSS and key
Before setting `false` to this value, please read and understand [sandbox documentation in Electron repo][sandbox doc] shortcut plugin). Before setting `false` to this value, please read and
to know what you're doing. understand [sandbox documentation in Electron repo][sandbox doc] to know what
you're doing.
Please note that this sandbox feature is different from Node.js integration in Electron. Node.js Please note that this sandbox feature is different from Node.js integration in
integration is always disabled. Electron. Node.js integration is always disabled.
### `keymaps` ### `keymaps`
@ -166,7 +192,8 @@ If an action name starts with `/`, it will navigate to the path. For example,
if you set `"/web/timelines/home"` to some key shortcut and you input the key, if you set `"/web/timelines/home"` to some key shortcut and you input the key,
browser will navigate page to `https://{your host}/web/timelines/home`. browser will navigate page to `https://{your host}/web/timelines/home`.
Below is a default path actions. They are corresponding the position of tab items. Below is a default path actions. They are corresponding the position of tab
items.
| Path | Description | Default Key | | Path | Description | Default Key |
|-------------------------------|-----------------------------------|-------------| |-------------------------------|-----------------------------------|-------------|
@ -177,8 +204,9 @@ Below is a default path actions. They are corresponding the position of tab item
| `/web/timelines/public` | Move to 'federated timeline' page | `5` | | `/web/timelines/public` | Move to 'federated timeline' page | `5` |
| `/web/getting-started` | Move to 'getting started' page | `6` | | `/web/getting-started` | Move to 'getting started' page | `6` |
If an action name ends with `.js`, it will run key shortcut plugin (please see below If an action name ends with `.js`, it will run key shortcut plugin (please see
'Key Shortcut Plugin' section). This plugin feature requires `"chromium_sandbox": true`. below 'Key Shortcut Plugin' section). This plugin feature requires
`"chromium_sandbox": true`.
By default, some key shortcuts for tab items are set in addition to above table. By default, some key shortcuts for tab items are set in addition to above table.
@ -230,21 +258,21 @@ By default, some key shortcuts for tab items are set in addition to above table.
## Multi account ## Multi account
If you set multiple accounts to `accounts` array in `config.json`, `Accounts` menu item will appear If you add multiple accounts to the `accounts` array in `config.json`, an
in application menu. `Accounts` menu item will appear in the application menu.
![multi account menu item](https://github.com/rhysd/ss/blob/master/Mstdn/multi-account.png?raw=true) ![multi account menu item](https://github.com/rhysd/ss/blob/master/Mstdn/multi-account.png?raw=true)
It will show the list of your account. Check mark is added for current user. It will show the list of your accounts. The check mark indicates the current
When you click menu item of non-current user, application window will be recreated and switch page user. When you click menu item of non-current user, application window will be
to the account. recreated and switch page to the account.
## Key Shortcut Plugin ## Key Shortcut Plugin
By specifying JavaScript file to action name in `keymaps` of `config.json`, you can write your By specifying JavaScript file to action name in `keymaps` of `config.json`, you
favorite behavior with JavaScript directly. Please note that `"chromium_sandbox" : true` can write your favorite behavior with JavaScript directly. Please note that
is also required (if you don't know what happens with `"chromium_sandbox" : true`, please read `"chromium_sandbox" : true` is also required (if you don't know what happens
above config section). with `"chromium_sandbox" : true`, please read the above config section).
```json ```json
{ {
@ -260,11 +288,13 @@ above config section).
} }
``` ```
The script file path is a relative path from your `Mstdn` application directory. For example, The script file path is a relative path from your `Mstdn` application directory.
Specifying `hello.js` will run `/Users/You/Application Support/Mstdn/hello.js` on Mac. For example, Specifying `hello.js` will run `/Users/You/Application
Support/Mstdn/hello.js` on Mac.
The plugin script MUST export one function. Function receives configuration object and current The plugin script MUST export one function. The function receives a
account object as its parameters. So above `hello.js` would look like: configuration object and the current account object as its parameters. So the
above `hello.js` would look like:
```js ```js
module.exports = function (config, account) { module.exports = function (config, account) {
@ -272,16 +302,19 @@ module.exports = function (config, account) {
} }
``` ```
With above example config, typing `r` will show 'Hello, {your name}' alert dialog. You can use any With above example config, typing `r` will show 'Hello, {your name}' alert
DOM APIs, Node.js's standard libraries and Electron APIs in plugin script. dialog. You can use any DOM APIs, Node.js's standard libraries and Electron APIs
in a plugin script.
## User CSS ## User CSS
When `user.css` is put in your `Mstdn` application directory, it will be loaded automatically. When `user.css` is put in your `Mstdn` application directory, it will be loaded
To enable this feature, `"chromium_sandbox" : true` is also required (if you don't know what happens automatically. To enable this feature, `"chromium_sandbox" : true` is also
with `"chromium_sandbox" : true`, please read above config section). required (if you don't know what happens with `"chromium_sandbox" : true`,
please read the above config section).
For example, below `/Users/You/Application Support/Mstdn/user.css` will change font color to red on Mac. For example, the below `/Users/You/Application Support/Mstdn/user.css` will
change font color to red on Mac.
```css ```css
body { body {
@ -293,15 +326,15 @@ body {
You can make a Node.js package which is run inner mastodon page. You can make a Node.js package which is run inner mastodon page.
Plugin is enabled if `chromium_sandbox` option is set to `false`. Please read above Plugin is enabled if `chromium_sandbox` option is set to `false`. Please read
configuration section before using any plugin. above configuration section before using any plugin.
### How to make a plugin ### How to make a plugin
Create `node_modules` directory in your application directory at first. And then, please make Create a `node_modules` directory in your application directory at first. And
`mstdn-plugin-hello` directory. It consists a node package. then, please make `mstdn-plugin-hello` directory. It consists a node package.
Package name must start with `mastdn-plugin-`. The package name must start with `mastdn-plugin-`.
Make `package.json` manually or by `$ npm init` in the directory. Make `package.json` manually or by `$ npm init` in the directory.
@ -326,9 +359,9 @@ module.exports = {
}; };
``` ```
Package must export one object. Each package must export one object. If the object has a function as a value of
If the object has a function as a value of `preload` key, it will be called at page being loaded. `preload` key, it will be called when the page is being loaded. The function
The function receives two parameters `config` and `account`. receives two parameters `config` and `account`.
By defining `keymaps` key you can define plugin-defined key shortcut action. By defining `keymaps` key you can define plugin-defined key shortcut action.
@ -346,13 +379,15 @@ module.exports = {
}; };
``` ```
The object of `keymaps` has keymap action name (key) and its handler (value). Here 'alert-hello' The `keymaps` object has keymap action name (key) and its handler (value).
key shortcut action is defined. Key shortcut handler takes 3 arguments. `config` and `account` Here 'alert-hello' key shortcut action is defined. Key shortcut handler takes 3
is the same as `preload`'s. `event` is a `KeyboardEvent` browser event on the key shortcut arguments. `config` and `account` is the same as `preload`'s. `event` is a
being called. You can cancel default event behavior by `.preventDefault()` method. `KeyboardEvent` browser event on the key shortcut being called. You can cancel
default event behavior using the `.preventDefault()` method.
User can specify the key shortcut as `plugin:{plugin name}:{action name}`. In above example, User can specify the key shortcut as `plugin:{plugin name}:{action name}`. In
`plugin:hello:alert-hello` is available in `keymaps` section in config.json. above example, `plugin:hello:alert-hello` is available in `keymaps` section in
config.json.
Note that you can use below APIs in the script. Note that you can use below APIs in the script.
@ -372,17 +407,18 @@ window.my_require = require;
### How to use ### How to use
If you didn't try above 'How to make' section, please install plugin package at first. If you didn't try above 'How to make' section, please install plugin package at
Below will install 'hello' plugin to `{app directory}/node_modules/mstdn-plugin-hello`. first. Below will install 'hello' plugin to `{app
directory}/node_modules/mstdn-plugin-hello`.
``` ```
$ cd {Your application directory} $ cd {Your application directory}
$ npm install mstdn-plugin-hello $ npm install mstdn-plugin-hello
``` ```
And then write what plugin should be loaded to `"plugins"` section of your account in `config.json`. And then write what plugin should be loaded to `"plugins"` section of your
`"hello"` should be added to the list. account in `config.json`. `"hello"` should be added to the list. If listed
If listed plugin defines some keymaps, you can specify it in `keymaps` section with plugin defines some keymaps, you can specify it in `keymaps` section with
`plugin:{name}:{action}` format. `plugin:{name}:{action}` format.
```json ```json
@ -410,10 +446,12 @@ If listed plugin defines some keymaps, you can specify it in `keymaps` section w
Note that you can enable different plugin for each your accounts. Note that you can enable different plugin for each your accounts.
Finally open Mstdn.app and see DevTools via [Menu] -> [View] -> [Developper Tools] -> console. Finally open Mstdn.app and open the DevTools via [Menu] -> [View] -> [Developper
If window is too small to see DevTools, please make window size bigger. Tools] -> console. If window is too small to see DevTools, please make window
size bigger.
In console, the message 'Hello from plugin!', config information and account information should be output. In the developer console, the message 'Hello from plugin!', config information
and account information should be output.
### List of Plugins ### List of Plugins
@ -421,10 +459,12 @@ To be made
## How to Debug ## How to Debug
By setting `NODE_ENV` environment variable to `development`, Mstdn will start in debug mode. By setting `NODE_ENV` environment variable to `development`, Mstdn will start in
debug mode.
In debug mode, app outputs all logs to stdout and opens DevTools for a page rendered in a window In debug mode, app outputs all logs to stdout and opens DevTools for a page
automatically. You can also see logs in 'console' tab of DevTools for debugging renderer process. rendered in a window automatically. You can also see logs in 'console' tab of
DevTools for debugging renderer process.
```sh ```sh
# If you installed this app via npm or yarn # If you installed this app via npm or yarn
@ -443,14 +483,16 @@ $ \path\to\Mstdn-win32-xxx-x.y.z\Mstdn.exe
## Contact to the Author ## Contact to the Author
Please feel free to make an issue on GitHub or mention on Mastodon/Twitter. Please feel free to create an issue on GitHub or mention me on Mastodon/Twitter.
- [@Linda\_pp@mstdn.jp](https://mstdn.jp/@Linda_pp) (Japanese account. English is also OK) - [@Linda\_pp@mstdn.jp](https://mstdn.jp/@Linda_pp) (Japanese account. English
is also OK)
- [@inudog@mastodon.social](https://mastodon.social/@inudog) (English account) - [@inudog@mastodon.social](https://mastodon.social/@inudog) (English account)
[Mastodon]: https://github.com/tootsuite/mastodon [Mastodon]: https://github.com/tootsuite/mastodon
[npm]: https://www.npmjs.com/package/mstdn [npm]: https://www.npmjs.com/package/mstdn
[yarn]: https://yarnpkg.com/en/package/mstdn [yarn]: https://yarnpkg.com/en/package/mstdn
[AUR]: https://aur.archlinux.org/packages/mstdn/
[Release page]: https://github.com/rhysd/Mstdn/releases [Release page]: https://github.com/rhysd/Mstdn/releases
[Electron]: https://electron.atom.io/ [Electron]: https://electron.atom.io/
[sandbox doc]: https://github.com/electron/electron/blob/master/docs/api/sandbox-option.md [sandbox doc]: https://github.com/electron/electron/blob/master/docs/api/sandbox-option.md