Merge branch 'develop'

nodsoft_moltenobsidian_web/vault/Getting Started.md

@@ -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 : 
@@ -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
 
@@ -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   
 

nodsoft_moltenobsidian_web/vault/Library/Markdown Conversion.md

@@ -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. 

nodsoft_moltenobsidian_web/vault/Vaults/FTP.md → nodsoft_moltenobsidian_web/vault/Library/Vaults Providers/FTP.md

@@ -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.

nodsoft_moltenobsidian_web/vault/Vaults/Filesystem.md → nodsoft_moltenobsidian_web/vault/Library/Vaults Providers/Filesystem.md

@@ -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");

nodsoft_moltenobsidian_web/vault/Vaults/HTTP.md → nodsoft_moltenobsidian_web/vault/Library/Vaults Providers/HTTP.md

@@ -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.