Skip to content

Commit

Permalink
Merge branch 'master' of github.com:Mara-Li/obsidian-mkdocs-publisher
Browse files Browse the repository at this point in the history
  • Loading branch information
@Mara-Li
Mara-Li committed Jun 14, 2022
2 parents c51f7b3 + 668261f commit c229a8e
Showing 1 changed file with 47 additions and 111 deletions.
158 changes: 47 additions & 111 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,24 @@
---
---
GitHub Publisher is a plugin that help you to send file in a configured GitHub Repository, based on a front matter entry state.

You can use it to send any markdown file, allowing compatibility thought a lot of Obsidian Publish alternative.

When a shared file is found, it will be sent in a new branch named by `your_vault_name-month-day-year`. A pull request followed by a merge will be done, and if everything is okay, the branch will be deleted after the merge.
Thus, you can easily revert commit, and create workflow based on PR, merged PR, specific push...

# Main configuration
# What the plugin do

- Read the frontmatter to check the value of a configured `share` key.
- Send the file (and their embedded image if any) to GitHub

But the plugin can do a lot more !
- Convert wikilinks to markdown links (without changing your file)
- Activate a GitHub action that have a `workflow_dispatche` event.
- Convert internal's links to match the configuration
- Clean your repo with removing deleted and unshared files
- Rename folder note with same name strategies with `index.md` (+ respecting the folder settings)

---
# Configuration

To use the plugin, you need to fill the correct information to allow the workflow.

Expand Down Expand Up @@ -35,29 +46,29 @@ Using the second option will activate two more options :
- Front matter key: The key you want to use in your file.
- Root folder : To prepend a path **before** the category key found (if any key are found!)

!!! EXAMPLE "Example"
- You use `category` in a file with `category: Roleplay/Characters/DND`
- You set a root folder with `_docs/pages`
- And you set a default folder on `_docs/draft`

The final path (in GitHub!) will be : `_docs/pages/Roleplay/Characters/DND`

But, if you don't set `category`, the path will be `_docs/draft`
> [!EXAMPLE] Example
> - You use `category` in a file with `category: Roleplay/Characters/DND`
> - You set a root folder with `_docs/pages`
> - And you set a default folder on `_docs/draft`
>
> The final path (in GitHub!) will be : `_docs/pages/Roleplay/Characters/DND`
>
> But, if you don't set `category`, the path will be `_docs/draft`
#### Fixed folder
Every file will be sent in the default folder. If you leave the default folder blank, it will be sent in the root of the repository.

!!! EXAMPLE "Example"
- If you set `source` for the default folder, any file will be sent in `your_repo/source`, whatever is their frontmatter key or their relative path.
- If you leave it blank, it will be sent in `your_repo` directly.
> [!example] Example
> - If you set `source` for the default folder, any file will be sent in `your_repo/source`, whatever is their frontmatter key or their relative path.
> - If you leave it blank, it will be sent in `your_repo` directly.
#### Obsidian Path
It uses the relative path in your Obsidian vault. The default folder will be prepended before the relative obsidian path. You can leave it blank to use the root repository.

!!! EXAMPLE "Example"
For a file in `20. Compendium/DND/Monster`
- If you set `source` : the final path will be `source/20. Compendium/DND/Monster`
- If you leave the default folder blank, the final path will be `20. Compendium/DND/Monster`
> [!example] Example
> For a file in `20. Compendium/DND/Monster`
> - If you set `source` : the final path will be `source/20. Compendium/DND/Monster`
> - If you leave the default folder blank, the final path will be `20. Compendium/DND/Monster`
### Workflow

Expand All @@ -73,15 +84,15 @@ You can also set up an "auto-delete" when you use the commands to delete files:

This option will also add a new command to delete file (without sharing new file).

!!! WARNING "WARNING"
You can't use the delete command if you don't have set a default folder (and a root folder if you use the YAML configuration)
Also, you can lost some files using this commands, so be careful! Don't forget that you can revert commit in case the plugin delete a file you don't want to delete.
>[!warning] Warning
> You can't use the delete command if you don't have set a default folder (and a root folder if you use the YAML configuration)
> Also, you can lost some files using this commands, so be careful! Don't forget that you can revert commit in case the plugin delete a file you don't want to delete.
!!! warning "Changing settings"
In case you change the folder configuration, the precedent file won't be deleted and result of a error of this workflow's part. Be careful!
>[!warning] Changing the option
> In case you change the folder configuration, the precedent file won't be deleted and result of a error of this workflow's part. Be careful!
You can set the path of the folder you want to avoid deleting the file. Separate folders a comma.
!!! Note "Regex are not supported here!"
>[!note] Regex are not supported here!
Finally, to prevent deleting `index` created outside of obsidian, you could use some parameters in your front matter :
- `autoclean: false`
Expand All @@ -90,25 +101,25 @@ Or removing the `share` key.

### Links' conversion

>[!note] These settings won't change your file's content in your vault
#### Index & folder note

Some publishing solution support folder note, but these note need to be named `index`. In case you use [Folder Note](https://github.com/aidenlx/alx-folder-note) with [the `same name` strategies](https://github.com/aidenlx/alx-folder-note/wiki/folder-note-pref) you will have a problem, no? By chance, I have a solution for you, guys!
Now, the plugin will convert these file into `index` if you activate the settings. Here some examples of renaming, using the different parameters from the default folder.

!!! example "frontmatter example with a file named `folder2`"
- Using a category value : `folder1/folder2`
- With root value named `docs` ⇒ `docs/folder1/folder2/index.md`
- Without root : `folder1/folder2/index.md`
- Without category value, with default folder named `drafts` : `draft/folder2.md` (the name won't be converted!)
> [!example] frontmatter example with a file named `folder2`
> - Using a category value : `folder1/folder2`
> - With root value named `docs` ⇒ `docs/folder1/folder2/index.md`
> - Without root : `folder1/folder2/index.md`
> - Without category value, with default folder named `drafts` : `draft/folder2.md` (the name won't be converted!)
!!! example "Example with Obsidian Path & a file named `folder2`"
With a path like : `folder1/folder2` the new path will be :
- If you use a default folder named `docs` : `docs/folder1/folder2/index.md`
- Without : `folder1/folder2/index.md`
> [!example] Example with Obsidian Path & a file named `folder2`
> With a path like : `folder1/folder2` the new path will be :
> - If you use a default folder named `docs` : `docs/folder1/folder2/index.md`
> - Without : `folder1/folder2/index.md`
!!! warning "This option doesn't work with fixed folder."

!!! note "These settings won't change your file's content in your vault"
>[!warning] This option doesn't work with fixed folder.
#### Internal links

Expand All @@ -129,81 +140,6 @@ You can configure :
- The share key used by the plugin. By default, it is `share`
- Folder excluded. The share key can't work here. Useful if you forget to remove the `share` (or turn it to `false`) and move a file in your archive…
- Add the command to share the file on the file menu (right-click on a file in the explorer or using the three dot) and editor menu (right-click on an opened edited note)

---
# Workflow example
## [Mkdocs Publisher](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/)
### Quick installation tutorial
1. Click on [use this template](https://github.com/obsidianMkdocs/obsidian-mkdocs-publisher-template/generate)[^1]
2. Use the name of your choice
3. Set and edit the `configuration.yml` in the root of the repository.

### Plugin configuration

![](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/assets/upload/obs2mk-1.png)
![](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/assets/upload/obs2mk-2.png)

1. Folder reception settings :
- Reception settings : `YAML frontmatter`
- Default folder : `docs/notes`
- Choose your frontmatter key, same as in `configuration.yml`, by default: `category`
- Root folder : `docs`
2. Workflow
- Leave blank the GitHub actions
- Auto-clean up : `TRUE`
- Excluded folder : `docs/assets/logo, docs/assets/js, docs/assets/css`[^3]
2. Images settings :
- Turn on transfer image
- Choose `docs/assets/img`
3. Folder note : `True`

The files (and the image) will be sent on your GitHub repository template, in the specified folder. The conversion will be done by the [github actions](https://github.com/Mara-Li/obsidian-mkdocs-publisher-template/blob/main/.github/workflows/ci.yml) when the branch were merged.

### Useful informations
#### Links
- [Obsidian Plugin](https://github.com/obsidianMkdocs/obsidian-github-publisher)
- [Python package](https://github.com/obsidianMkdocs/obsidian-mkdocs-publisher-python)
- [Template](https://github.com/obsidianMkdocs/obsidian-mkdocs-publisher-template)

#### How to...
- [Configure the blog](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/documentation/create%20the%20blog/)
- [Customize the blog](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/documentation/blog%20customization/)
- [Copy the link ?](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/documentation/useful%20plugins/#metacopy)
- [Update the template](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/documentation/Q%26A/#2-update-the-template)

#### Support
- [x] Wikilinks (`[[Links]]`)
- [x] File transclusion/embed, both wikilinks and markdown links
- [x] Obsidian callout and custom callout
- [x] Folder notes and their citation
- [x] Custom attributes
- [x] Sharing state and custom folder hierarchy.
- [x] Mobile and desktop
- [x] File mini preview on Hover

#### Limitations
- No plugins (dataview...)
- No graph view
- You need to have a clean tree structure with unique name file. No worry about the display in blog ; the `title` key in frontmatter will change it, so you can have a `ezarezozre` name and use a good title like `reading book`.
- I prefer to encourage you to use the `shortlinks` option in obsidian’s link option.
- Obs2mk will don’t move the file if you change the `category` value : you need to manually delete it to prevent duplicate.


---
## [Digital Garden](https://github.com/TuanManhCao/digital-garden)

![](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/assets/upload/digital-garden-1.png)
![](https://obsidianmkdocs.github.io/obsidian_mkdocs_publisher_docs/assets/upload/digital-garden-2.png)

1. Folder reception settings :
- Reception settings : `Obsidian Path`
- Default folder : `posts`
2. Workflow :
- Leave blank
- Turn on autoclean
3. Images settings :
- Transfer image on true
- Default folder : `posts/Attachments`
---
If you find this plugin and workflow useful, you can give me some coffee money.
<a href='https://ko-fi.com/X8X54ZYAV' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
Expand Down

0 comments on commit c229a8e

Please sign in to comment.