generated from obsidianmd/obsidian-sample-plugin
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
110 additions
and
69 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,96 +1,137 @@ | ||
# Obsidian Sample Plugin | ||
# HashDian Plugin | ||
|
||
This is a sample plugin for Obsidian (https://obsidian.md). | ||
Hash-Dian is an Obsidian plugin designed to simplify the process of publishing notes directly to your Hashnode blog. | ||
|
||
This project uses Typescript to provide type checking and documentation. | ||
The repo depends on the latest plugin API (obsidian.d.ts) in Typescript Definition format, which contains TSDoc comments describing what it does. | ||
## Features | ||
|
||
**Note:** The Obsidian API is still in early alpha and is subject to change at any time! | ||
- Publish notes directly to your Hashnode blog. | ||
- Provides basic and advanced templates to configure the Hashnode blog for hustle free publishing | ||
- Integrates seamlessly with Obsidian's existing interface. | ||
|
||
This sample plugin demonstrates some of the basic functionality the plugin API can do. | ||
- Adds a ribbon icon, which shows a Notice when clicked. | ||
- Adds a command "Open Sample Modal" which opens a Modal. | ||
- Adds a plugin setting tab to the settings page. | ||
- Registers a global click event and output 'click' to the console. | ||
- Registers a global interval which logs 'setInterval' to the console. | ||
## Installation | ||
|
||
## First time developing plugins? | ||
Currently, the plugin is not available in the Obsidian community plugins list. You will need to manually install it. Follow these steps: | ||
|
||
Quick starting guide for new plugin devs: | ||
- Download the latest release from the releases page. | ||
- Extract the downloaded zip file. | ||
- Copy the extracted folder to your Obsidian vault's `.obsidian/plugins/` directory. | ||
- Enable the plugin in Obsidian's settings. | ||
|
||
- Check if [someone already developed a plugin for what you want](https://obsidian.md/plugins)! There might be an existing plugin similar enough that you can partner up with. | ||
- Make a copy of this repo as a template with the "Use this template" button (login to GitHub if you don't see it). | ||
- Clone your repo to a local development folder. For convenience, you can place this folder in your `.obsidian/plugins/your-plugin-name` folder. | ||
- Install NodeJS, then run `npm i` in the command line under your repo folder. | ||
- Run `npm run dev` to compile your plugin from `main.ts` to `main.js`. | ||
- Make changes to `main.ts` (or create new `.ts` files). Those changes should be automatically compiled into `main.js`. | ||
- Reload Obsidian to load the new version of your plugin. | ||
- Enable plugin in settings window. | ||
- For updates to the Obsidian API run `npm update` in the command line under your repo folder. | ||
## Configure Settings | ||
|
||
## Releasing new releases | ||
To configure Hash-Dian, you need to set up two pieces of information: the Hashnode Personal Access Token and the Hashnode Personal Publication Id. | ||
|
||
- Update your `manifest.json` with your new version number, such as `1.0.1`, and the minimum Obsidian version required for your latest release. | ||
- Update your `versions.json` file with `"new-plugin-version": "minimum-obsidian-version"` so older versions of Obsidian can download an older version of your plugin that's compatible. | ||
- Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix `v`. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases | ||
- Upload the files `manifest.json`, `main.js`, `styles.css` as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release. | ||
- Publish the release. | ||
### Hashnode Personal Access Token | ||
|
||
> You can simplify the version bump process by running `npm version patch`, `npm version minor` or `npm version major` after updating `minAppVersion` manually in `manifest.json`. | ||
> The command will bump version in `manifest.json` and `package.json`, and add the entry for the new version to `versions.json` | ||
The Personal Access Token is like a private key to your Hashnode account. You can use this personal access token to interact with your Hashnode account using the Hashnode API. Here is how to generate your Hashnode Developer Access Token: | ||
|
||
## Adding your plugin to the community plugin list | ||
1. Log in to your Hashnode account. | ||
2. Click on your profile picture at the bottom-left corner of the page on desktop screen or top-right corner on mobile screen. | ||
3. Click on the Account Settings option from the popup modal to access the settings page. | ||
4. Click on the DEVELOPER tab. | ||
5. Click the Generate New Token button to generate a new token for your account. | ||
6. Copy auto-generated token in the Your Tokens section. | ||
7. Go to Obsidian's settings and paste the token in HashDian Community Settings `Hashnode Personal Access Token`. | ||
|
||
- Check https://github.com/obsidianmd/obsidian-releases/blob/master/plugin-review.md | ||
- Publish an initial version. | ||
- Make sure you have a `README.md` file in the root of your repo. | ||
- Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin. | ||
### Hashnode Personal Publication Id | ||
|
||
## How to use | ||
The ID of publication the post belongs to.This can be found in your Hashnode Dashboard url : `https://hashnode.com/{Publication Id}/dashboard`. | ||
|
||
- Clone this repo. | ||
- Make sure your NodeJS is at least v16 (`node --version`). | ||
- `npm i` or `yarn` to install dependencies. | ||
- `npm run dev` to start compilation in watch mode. | ||
Copy the Publication ID and paste it in HashDian Community Settings `Hashnode Personal Publication Id`. | ||
|
||
## Manually installing the plugin | ||
### Usage | ||
|
||
- Copy over `main.js`, `styles.css`, `manifest.json` to your vault `VaultFolder/.obsidian/plugins/your-plugin-id/`. | ||
Once installed, you can access Hash-Dian from Obsidian's command palette. In Obsidian, the command palette is a powerful tool that allows you to quickly perform operations. For the Hash-Dian plugin, you can add three operations: "Publish to Hashnode", "Basic Hashnode Blog Template", and "Advanced Hashnode Blog Template". | ||
|
||
## Improve code quality with eslint (optional) | ||
- [ESLint](https://eslint.org/) is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code. | ||
- To use eslint with this project, make sure to install eslint from terminal: | ||
- `npm install -g eslint` | ||
- To use eslint to analyze this project use this command: | ||
- `eslint main.ts` | ||
- eslint will then create a report with suggestions for code improvement by file and line number. | ||
- If your source code is in a folder, such as `src`, you can use eslint with this command to analyze all files in that folder: | ||
- `eslint .\src\` | ||
### Publish to Hashnode | ||
|
||
## Funding URL | ||
This operation allows users to publish their notes directly to their Hashnode blog. This command parses the markdown content the user currently in and extracts the meta data, blog content and convert it into the format required by the Hashnode API, and then send a POST request to the API endpoint for creating a new post. | ||
|
||
You can include funding URLs where people who use your plugin can financially support it. | ||
### Basic Hashnode Blog Template | ||
|
||
The simple way is to set the `fundingUrl` field to your link in your `manifest.json` file: | ||
This operation should allow users to apply basic template which is enough to publish a Hashnode blog. This command inserts the below properties for your blog: | ||
|
||
```json | ||
{ | ||
"fundingUrl": "https://buymeacoffee.com" | ||
} | ||
```yaml | ||
|
||
--- | ||
title: | ||
subtitle: | ||
coverImageURL.coverImageOptions: | ||
tags: | ||
- | ||
--- | ||
|
||
``` | ||
|
||
### Advanced Templates | ||
|
||
This operation is similar to "Basic Hashnode Blog Template", but it allows users to apply more complete payload required for POST Call [hashnode publishPost mutation payload](https://apidocs.hashnode.com/#definition-PublishPostInput) | ||
|
||
## Contributing to Hash-Dian | ||
|
||
We welcome contributions from everyone! We believe that our project is only as strong as our community. Here are some ways you can contribute to the Hash-Dian project: | ||
|
||
### Step 1: Fork the Repository | ||
|
||
Before you start contributing, you'll need to fork the repository. This creates a copy of the repository in your GitHub account. Once you've done that, clone the repository to your local machine: | ||
|
||
```bash | ||
git clone https://github.com/YOUR_USERNAME/hash-dian.git | ||
``` | ||
|
||
If you have multiple URLs, you can also do: | ||
Replace `YOUR_USERNAME` with your GitHub username. | ||
|
||
### Step 2: Set Up Your Development Environment | ||
|
||
Once you've cloned the repository, navigate into the project directory and install the dependencies: | ||
|
||
```json | ||
{ | ||
"fundingUrl": { | ||
"Buy Me a Coffee": "https://buymeacoffee.com", | ||
"GitHub Sponsor": "https://github.com/sponsors", | ||
"Patreon": "https://www.patreon.com/" | ||
} | ||
} | ||
```bash | ||
cd hash-dian | ||
npm install | ||
``` | ||
|
||
## API Documentation | ||
This will install all the necessary dependencies for the project. | ||
|
||
### Step 3: Make Your Changes | ||
|
||
Now you're ready to start making changes. Create a new branch for your feature or bugfix: | ||
|
||
```bash | ||
git checkout -b my-feature-branch | ||
``` | ||
|
||
Replace `my-feature-branch` with a descriptive name for your branch. This keeps your changes organized and separates them from the main project. | ||
|
||
Make your changes in this branch, then commit them: | ||
|
||
```bash | ||
git add . | ||
git commit -m "Add my feature" | ||
``` | ||
|
||
Again, replace `"Add my feature"` with a meaningful commit message that describes your changes. | ||
|
||
### Step 4: Push Your Changes | ||
|
||
After committing your changes, push them to your GitHub repository: | ||
|
||
```bash | ||
git push origin my-feature-branch | ||
``` | ||
|
||
Replace `my-feature-branch` with the name of your branch. | ||
|
||
### Step 5: Open a Pull Request | ||
|
||
Go to your repository on GitHub and click on the "New Pull Request" button. Select your feature branch as the source, and the main branch as the destination. Then, describe your changes and submit the pull request. | ||
|
||
### Other Ways to Contribute | ||
|
||
Contributions aren't limited to code. You can also contribute by: | ||
|
||
- Reporting bugs | ||
- Suggesting new features | ||
- Improving documentation | ||
- Reviewing pull requests | ||
|
||
See https://github.com/obsidianmd/obsidian-api | ||
We appreciate all types of contributions and we're here to help you get started. |