User Guide
Joplin Pages Publisher is really easy to use. Just follow these 6 steps(within 5 minutes):
Get a Github account, and generate a Github token(For common users, scope public_repo is enough), copy it to Joplin Setting Panel of Pages Publisher.
Related Github docs about token(If you are concerned):
Joplin -> Menu -> Tools -> Open Pages Publisher, to open this plugin's UI.
Now you can see four tabs on top:
- Site
- Pages
- Articles
- Github
In Site panel, you can define some global data and behavior for you site.
The Theme is the most important configuration item. A theme is a set of pages' templates and configuration. There is a built-in available theme named "Default". Creating you own theme is possible, but in this guide, we'll use the Default theme.
Within the Default theme, Site Name field is required. Fill it and save Site configuration.
In Pages panel, we see four pages in list. This means there will be four types of page in our site, defined by the Default theme.
These four pages are all customizable, which means we can define some data or behavior for that page. Please customize them one by one, as you like.
In Articles panel, You can search some Joplin notes and add them to Published area. Notes in Published area will be transformed to HTML documents, using the template defined by theme.
In Github panel, fill in your github information. For common users, User Name and Email will be enough.
Click Generate button, all necessary files of your site will be generated. And then click Publish button, they will be pushed into your Github repository.
Congratulation, Your Github Pages website is ready now!
Q: Does this plugin support extended Markdown syntaxes in my notes?
A: Yes. This plugin will respect all extended Markdown syntaxes enabled in Joplin Setting.
Q: Does this plugin support transforming Joplin Markdown Link?
A: Yes. But linked notes must be published articles, too.
Q: What should I do if I have already got an existing username.github.io repository?
A: You need do nothing special, just fill your Github information as usual. Attention: default target branch of Page Publisher is main, if your existing repository are using non-main branch(for example, master), you should set the right target branch in this plugin.
Q: Does this plugin use something like git push -f, which will mess up my commit history?
A: No. No git push -f is used.
Q: I'm in China and Publishing failed!
A: Retry several times, or use a network proxy to connect to Github.