Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
SakuraIsayeki committed Jul 6, 2024
2 parents 1fa1b66 + 1ea758a commit 312ed42
Show file tree
Hide file tree
Showing 6 changed files with 67 additions and 7 deletions.
9 changes: 5 additions & 4 deletions nodsoft_moltenobsidian_web/vault/Getting Started.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ As all tool-related operations are detailed on [[Tool/Index|the tool's readme]],
The MoltenObsidian library can be found on [NuGet](https://www.nuget.org/packages?q=Tags:"moltenobsidian"). Here's a rundown of the main packages you'll be using :
- [`Nodsoft.MoltenObsidian`](https://www.nuget.org/packages/Nodsoft.MoltenObsidian): The backbone of the library. Include this package if none other, as it is implicitly referenced by all other packages.
- [`Nodsoft.MoltenObsidian.Blazor`](https://www.nuget.org/packages/Nodsoft.MoltenObsidian.Blazor): The Blazor integration. This package provides a turnkey solution for Blazor Server, United, and WASM based applications.
- [[Vaults/Index|A vault provider]]: One of them will be required to import a vault.
- [[Library/Vaults Providers/Index|A vault provider]]: One of them will be required to import a vault.

Package installation follows the same pattern as other NuGet packages.
Use your IDE's package manager, or run these commands within the root of your .NET project :
Expand Down Expand Up @@ -46,8 +46,9 @@ And a paragraph with **bold** and *italic* text.
// This is the HTML string you can then call in Blazor components as `@htmlText`.
MarkupString htmlText = obsidianMarkdown.ToHtml();
```
But that's just the basics. Under the hood, [Markdig](https://github.com/xoofx/markdig) is what makes it happen. Easy!
But that's just the basics. Under the hood, [Markdig](https://github.com/xoofx/markdig) is what makes it happen. Easy!

Check out [[Markdown Conversion]] for more on converting raw markdown.

## Setting up a vault

Expand All @@ -67,13 +68,13 @@ public void ConfigureServices(IServiceCollection services)
}
```
*`_Imports.razor`*
```razor
```csharp
@using Nodsoft.MoltenObsidian.Blazor
@using Nodsoft.MoltenObsidian.Blazor.Helpers;
@using Nodsoft.MoltenObsidian.Vault;
```
*`VaultPage.razor`*
```razor
```csharp
@page "/vault/{*VaultPath}"
@inject IVault Vault

Expand Down
59 changes: 59 additions & 0 deletions nodsoft_moltenobsidian_web/vault/Library/Markdown Conversion.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
order: 1
---


# Markdown Conversion

Converting Obsidian-flavoured markdown to HTML in a standalone manner is a very straightforward task, using MoltenObsidian. Dealing with a standalone markdown file, nothing more than the base [`Nodsoft.MoltenObsidian`](https://www.nuget.org/packages/Nodsoft.MoltenObsidian) library is needed. You won't be importing entire vaults, merely declaring your markdown text, and that's it.

## The Basics

It all starts with the [`ObsidianText`](https://github.com/Nodsoft/MoltenObsidian/blob/main/Nodsoft.MoltenObsidian/ObsidianText.cs) object.
Using its `.ToHtml()` method provides a turnkey solution for rendering Markdown to HTML using sensible defaults similar to the parsing/rendering rules found in Obsidian.
```csharp
using Nodsoft.MoltenObsidian;

// Create a new ObsidianText instance with the content to convert
ObsidianText markdown = new(@"
# This is a Markdown header
This is a Markdown paragraph.
");

// Convert to HTML
string html = markdown.ToHtml()

// Our `html` string then equates to this :
/*
<h1 id="this-is-a-markdown-header">This is a Markdown header</h1>
<p>This is a Markdown paragraph.</p>
*/
```

## Customizing the converter
MoltenObsidian uses [Markdig](https://github.com/xoofx/markdig/) as its Markdown engine. This allows us to provide downstream developers with great extensibility when it comes to Markdown parsing and rendering. On top of [implementing its own specs](https://github.com/xoofx/markdig/tree/master/src/Markdig.Tests/Specs) (some of which aren't implemented within Obsidian), it allows us to provide the appropriate extensions for any Obsidian-specific syntax, such as [Internal Links](https://help.obsidian.md/Linking+notes+and+files/Internal+links) and [Tags](https://help.obsidian.md/Editing+and+formatting/Tags).
However, there are instances where a downstream developer may want to further customize the pipeline, to add, remove, or alter certain conversion elements.

Internally, all conversion done in `ObsidianText` instances is handled by the Default [`ObsidianHtmlConverter`](https://github.com/Nodsoft/MoltenObsidian/blob/main/Nodsoft.MoltenObsidian/Converter/ObsidianHtmlConverter.cs), which wraps around a `MarkdownPipeline`. Building this pipeline from Obsidian defaults can be achieved using the [`ObsidianPipelineBuilder`](https://github.com/Nodsoft/MoltenObsidian/blob/main/Nodsoft.MoltenObsidian/Converter/ObsidianPipelineBuilder.cs), which provides the base defaults for the entire library.
Downstream developers wishing to customize further their converter whilst keeping in sync with future MoltenObsidian releases are encouraged to use the `ObsidianPipelineBuilder` as baseline for their custom pipeline needs.

> [!NOTE]
> Internal Links support is only enabled on `ObsidianText` instances supplied by a vault, due to cross-references.
> Without the vault validating an internal link, it will be ignored on rendering.

## Frontmatter parsing
Per Obsidian's markdown specifications, any markdown text can be prefaced with a [YAML](https://yaml.org) Frontmatter section (dubbed [Properties](https://help.obsidian.md/Editing+and+formatting/Properties) by Obsidian in newer versions) :
```
---
name: "Example"
description: "Instead of describing this note, i'll tell you a secret : This will never be displayed!"
---

# This is a Markdown header

This is a Markdown paragraph.
```

This Frontmatter section is omitted from HTML render, however is retained under `ObsidianText.Frontmatter`, which is a `Dictionary<string, object>` property. This allows any markdown note to pass metadata about its content, and allows MoltenObsidian to control a note's behaviour in vaults.
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ public void ConfigureServices(IServiceCollection services)
```

Alternatively you can instantiate your own FTP vault like so:
```cs
```csharp
using Nodsoft.MoltenObsidian.Vaults.Ftp;

// Instantiate the FtpClient.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ public void ConfigureServices(IServiceCollection services)
```

Alternatively you can instantiate your own Filesystem vault like so:
```cs
```csharp
using Nodsoft.MoltenObsidian.Vaults.FileSystem;

IVault vault = FileSystemVault.FromDirectory("/path/to/vault");
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ public void ConfigureServices(IServiceCollection services)
```

Alternatively you can instantiate your own HTTP/HTTPS vault like so:
```cs
```csharp
using Nodsoft.MoltenObsidian.Vaults.Http;

// Instantiate the HttpClient.
Expand Down

0 comments on commit 312ed42

Please sign in to comment.