|
1 # Include Mastodon Feed Wordpress Plugin |
|
2 |
|
3 Plugin that provides an `[include-mastodon-feed]` shortcode to easily integrate mastodon feeds into wordpress pages. Supports personal and tag feeds. |
|
4 |
|
5 The plugin is written in PHP and generates native JavaScript to fetch and render the mastodon feed. No special libraries needed. |
|
6 |
|
7 ## Table of contents |
|
8 * [Usage](#usage) |
|
9 * [Supported shortcode attributes](#supported-shortcode-attributes) |
|
10 * [Additional customization](#additional-customizations) |
|
11 * [Installation](#installation) |
|
12 * [Installation via ZIP file](#installation-via-zip-file) |
|
13 * [Installation via git checkout](#installation-via-git-checkout) |
|
14 * [Known issues](#known-issues) |
|
15 * [Todo](#todo) |
|
16 * [FAQ](#faq) |
|
17 * [How do I find my account ID?](#how-do-i-find-my-account-id) |
|
18 * [Can I modify the plugin?](#can-i-modify-the-plugin) |
|
19 |
|
20 ## Usage |
|
21 |
|
22 Place the following shortcode right into the page. Either as shortcode block or just copy and paste right within a text block: |
|
23 |
|
24 ```[include-mastodon-feed instance="YOUR-INSTANCE" account="YOUR-ACCOUNT-ID"]``` |
|
25 |
|
26 ### Supported shortcode attributes |
|
27 |
|
28 | Attribute | Default value | Example | Description | |
|
29 | ------------------- | ----------------------------- | ------------------------- | ----------------------------------------------------------------- | |
|
30 | **account** | | id="012345678910" | (required attribute) Your account ID ([a long number](#how-do-i-find-my-account-id)) | |
|
31 | tag | | tag="travel" | use **tag** instead of **account** if you want to embed a tag feed instead of a personal feed | |
|
32 | **instance** | | instance="example.org" | (required attribute) Domain name of the instance without https:// | |
|
33 | limit | 20 | limit="10" | Maximum number of statuses | |
|
34 | excludeBoosts | false | excludeBoosts="true" | Exclude boosted statuses | |
|
35 | excludeReplies | false | excludeReplies="true" | Exclude replies to other accounts | |
|
36 | excludeConversationStarters | false | excludeConversationStarters="true" | Exclude statuses that start with a user mention | |
|
37 | onlyPinned | false | onlyPinned="true" | Show only pinned statuses | |
|
38 | onlyMedia | false | onlyMedia="true" | Show only statuses containing media | |
|
39 | preserveImageAspectRatio | false | preserveImageAspectRatio="true" | Preserve image aspect ratio | |
|
40 | tagged | false | tagged="tagname" | Show only statuses that are tagged with given tag name (no #!) | |
|
41 | linkTarget | "_self" | linkTarget="_blank" | Target for all links | |
|
42 | showPreviewCards | true | showPreviewCards="false" | Show preview cards | |
|
43 | hideStatusMeta | false | hideStatusMeta="true" | Hide status meta information (automatically also hides date and time) | |
|
44 | hideDateTime | false | hideDateTime="true" | Hide date and time from status meta information | |
|
45 | darkmode | false | darkmode="true" | Enable dark mode | |
|
46 | text-loading | "Loading Mastodon feed..." | text-loading="Loading ⏳" | Loading text | |
|
47 | text-noStatuses | "No statuses available" | text-noStatuses="💩" | Text if no statuses are available | |
|
48 | text-boosted | "boosted 🚀" | text-boosted="🚀" | Boosted status indicator text | |
|
49 | text-viewOnInstance | "view on instance" | text-viewOnInstance="🔗" | View status on instance link text | |
|
50 | text-showContent | "Show content" | text-showContent="👀" | Text for content warning buttons | |
|
51 | text-permalinkPre | "on" | text-showContent="📅" | Text before post permalink (date & time) | |
|
52 | text-permalinkPost | "" | text-showContent="📅" | Text after post permalink (date & time) | |
|
53 | text-edited | "(edited)" | text-showContent="✏" | Text indicating edited posts | |
|
54 | date-locale | "en-US" | date-locale="de-DE" | Locale for date string, used in toLocaleString() | |
|
55 | date-options | "{}" | date-options="{dateStyle: 'short', timeStyle: 'long'}" | Format options directly fed into toLocaleString() | |
|
56 |
|
57 ### Additional customizations |
|
58 |
|
59 You can define several plugin constants to set custom default options that will be applied site-wide. |
|
60 |
|
61 1. Open your `wp-config.php` file |
|
62 2. Search for the line `/* Add any custom values between this line and the "stop editing" line. */` |
|
63 3. Define the options you want to override between this line and `/* That's all, stop editing! Happy publishing. */` |
|
64 |
|
65 See [config-example.php](config-example.php) for a full list of supported settings. |
|
66 |
|
67 ## Installation |
|
68 |
|
69 The plugin is available through the official Wordpress plugin directory https://wordpress.org/plugins/include-mastodon-feed/ |
|
70 |
|
71 1. Log into your Wordpress installation |
|
72 2. Go to "Plugins" and select "Add New" |
|
73 3. Search for "Include Mastodon Feed" |
|
74 4. Hit the "Install" button |
|
75 5. After installation hit the "Activate" button |
|
76 |
|
77 ### Installation via ZIP file |
|
78 |
|
79 1. Click on the `<>Code` in the top right of this page |
|
80 2. Select `Download ZIP` |
|
81 3. Create a `include-mastodon-feed` folder in your Wordpress plugins directory |
|
82 4. Unpack all the files from the ZIP there (files only, no sub-directory) |
|
83 5. Enable plugin in Wordpress |
|
84 6. Use shortcode |
|
85 |
|
86 ### Installation via git checkout |
|
87 |
|
88 If you are familiar with Github you can clone the repository right into your Wordpress plugins folder |
|
89 |
|
90 1. SSH into your webserver |
|
91 2. `cd /path/to/wordpress/wp-content/plugins` |
|
92 3. `git clone https://github.com/wolfgang101/include-mastodon-feed.git` |
|
93 4. Enable plugin in Wordpress |
|
94 5. Use shortcode |
|
95 |
|
96 ## Known issues |
|
97 |
|
98 ### Todo |
|
99 |
|
100 * improve support for video and audio media attachment types |
|
101 * integrate i18n into translate.wordpress.org instead of text constants |
|
102 * re-build plugin as custom gutenberg block |
|
103 |
|
104 ## FAQ |
|
105 |
|
106 ### How do I find my account ID? |
|
107 As an instance admin you can easily read your user ID in the admin backend. As regular user you can try an API v2 search to find your ID |
|
108 |
|
109 Use the following URL to get your ID: |
|
110 |
|
111 ```https://example.org/api/v2/search?q=username@example.org&resolve=true&limit=5``` |
|
112 |
|
113 * Change `example.org` to your instance |
|
114 * Replace `username` with your handle. |
|
115 * Open the URL in your webbrowser |
|
116 |
|
117 **Note:** You must be logged in to do that |
|
118 |
|
119 ### Can I modify the plugin? |
|
120 The plugin is released unter the [Expat License](LICENSE) which is very permissive. Knock youself out! |