ObsidianHtml

https://obsidian-html.github.io/
Admin
ObsidianHtml is a Python tool that converts Obsidian vaults into static HTML websites with features...
Tokens:102,885
Snippets:2,570
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example accept invocation

Source: https://obsidian-html.github.io/configurations/modules/developer-documentation/running-a-binary-module.html

A concrete example of an accept command execution.

```bash
[ DEBUG ] * running: /home/user/git/rust/obshtml-example/target/release/obshtml-example accept /home/user/git/obsidian-html/output/mod 2023-05-26T23:26:26.259320_BinaryModule_rust_example_module
```

--------------------------------

### Module interaction logging example

Source: https://obsidian-html.github.io/configurations/modules/developer-documentation/module-design.html

Example log output showing how module dependencies and file alterations are tracked.

```text
ModuleA created [config.json]
ModuleB used config.json; created [tags.json, nodes.json] and altered [config.json]
```

--------------------------------

### Install ObsidianHtml versions

Source: https://obsidian-html.github.io/instructions/installation.html

Commands to install either the stable PyPi release or the latest development build from GitHub.

```bash
pip install obsidianhtml
```

```bash
pip install git+https://github.com/obsidian-html/obsidian-html
```

--------------------------------

### Install and Run Obsidian-HTML from Code

Source: https://obsidian-html.github.io/instructions/run-custom-code.html

Instructions for cloning the repository, installing dependencies, and running Obsidian-HTML directly from the source code. This is useful for testing changes or customizing the code.

```bash
git clone git@github.com:obsidian-html/obsidian-html.git

cd obsidian-html

pip install .

python -m obsidianhtml -i /path/to/config.yml
```

--------------------------------

### Test ObsidianHtml Installation

Source: https://obsidian-html.github.io/instructions/install-a-different-version.html

Run this command after installation to verify that you are running the correct version. The output will indicate the version and any specific test branch information.

```bash
$ obsidianhtml --test
test 3.2.0 shutil test
```

--------------------------------

### Install ObsidianHtml

Source: https://obsidian-html.github.io/instructions/quickstart.html

Install the ObsidianHtml package using pip. This command fetches and installs the latest stable version.

```bash
pip install obsidianhtml

```

--------------------------------

### Define module configuration

Source: https://obsidian-html.github.io/configurations/modules/developer-documentation/running-a-binary-module.html

Example configuration structure for binary modules.

```yaml
module_config: 
  rust_example_module:
    b: "serious stuff"
  hello:
    b: "hello there"
```

--------------------------------

### Define module list

Source: https://obsidian-html.github.io/configurations/modules/developer-documentation/running-a-binary-module.html

Example module list registration for binary modules.

```yaml
module_list:
  preparation:
    # other modules excluded for brevity
    # (...)

    - name: rust_example_module   
      description: Does nothing, just tests the Binary module
      binary: /home/user/git/rust/obshtml-example/target/release/obshtml-example

    - name: hello   
      description: Does nothing, just tests the Binary module
      binary: /home/user/git/rust/obshtml-example/target/release/obshtml-example
```

--------------------------------

### Serve Website Locally

Source: https://obsidian-html.github.io/instructions/quickstart.html

Start a local web server to preview the generated HTML files.

```bash
obsidianhtml serve --directory output/html --port 8000
```

--------------------------------

### Module output example

Source: https://obsidian-html.github.io/configurations/modules/developer-documentation/running-a-binary-module.html

Expected debug output from the module.

```text
[    Debug    ]   rust_example_module - serious stuff
[    Debug    ]   hello - hello there
```

--------------------------------

### Clone Example Vault

Source: https://obsidian-html.github.io/instructions/tutorials/tutorial-installation-on-windows.html

Use git to clone the example vault repository. This is useful for testing Obsidian HTML if you don't have your own vault readily available.

```bash
git clone https://github.com/obsidian-html/example_vault.git

```

--------------------------------

### Install virtualenv package

Source: https://obsidian-html.github.io/instructions/tutorials/tutorial-installation-on-windows.html

Installs the virtualenv package using pip. This is a prerequisite for creating virtual environments.

```bash
python -m ensurepip
python -m pip install virtualenv
```

--------------------------------

### Test Python Installation

Source: https://obsidian-html.github.io/instructions/tutorials/specifics/bootstrapping-python-on-windows.html

Verify that the Python executable is accessible and functional after manual installation. Ensure the path is correct for your downloaded Python version.

```bash
C:\Users\User\Downloads\python-3.10.7\python.exe --version
```

--------------------------------

### Install Master Branch of ObsidianHtml

Source: https://obsidian-html.github.io/instructions/install-a-different-version.html

Use this command to uninstall the current version and install the latest development version from the master branch.

```bash
pip uninstall obsidianhtml
pip install git+https://github.com/obsidian-html/obsidian-html.git
```

--------------------------------

### Module List Configuration

Source: https://obsidian-html.github.io/configurations/modules/developer-documentation/module-design.html

Modules are listed and described in the `module_list` section of `config.yml`. This example shows the `prepare_output_folders` module with its name and description.

```yaml
module_list:
  preparation:
    - name: prepare_output_folders
      description:
        - Ensures the output folders are created
        - Optionally removes previous output if it exists in the target directories
```

--------------------------------

### Install pythonnet on Windows

Source: https://obsidian-html.github.io/instructions/installation.html

Required dependency for running ObsidianHtml on Windows systems.

```bash
pip install --pre pythonnet
```

--------------------------------

### Basic ObsidianHtml Configuration

Source: https://obsidian-html.github.io/instructions/quickstart.html

Example configuration file for ObsidianHtml. Specify the path to your Obsidian vault.

```yaml
# The first folder that contains all obsidian files
# Use full path or relative path, but don't use ~/
obsidian_folder_path_str: '/path/to/your/vault' 

# The note that will be used as the index.html 
# should be in obsidian_folder_path_str

```

--------------------------------

### Get Help for Obsidian HTML Commands

Source: https://obsidian-html.github.io/instructions/obsidianhtml-run.html

Run this command to display all available options and commands for obsidianhtml, including detailed information on the `run` command.

```bash
obsidianhtml help
```

--------------------------------

### Navigate to Cloned Folder

Source: https://obsidian-html.github.io/instructions/tutorials/tutorial-installation-on-windows.html

Change the current directory to the newly cloned example vault folder.

```bash
cd example_vault

```

--------------------------------

### Configure HTML URL Prefix

Source: https://obsidian-html.github.io/instructions/snippets/deployment-instructions.html

Set the base path for websites hosted in a subfolder. Ensure the value starts with a slash and excludes a trailing slash.

```yaml
# Use when deploying to https://mydomain.com/html_prefix/ instead of https://mydomain.com/
# use '/html_prefix' (prepend slash, no slash at the end)
html_url_prefix: '/subfolder'
```

--------------------------------

### Install Obsidian HTML

Source: https://obsidian-html.github.io/instructions/tutorials/tutorial-installation-on-windows.html

Install the Obsidian HTML package using pip. After installation, you can check the version using 'obsidianhtml version'.

```bash
pip install obsidianhtml

```

```bash
obsidianhtml version

```

--------------------------------

### Install Pythonnet on Windows

Source: https://obsidian-html.github.io/instructions/quickstart.html

Install the pythonnet package, which is required when running on Windows for Python integration.

```bash
pip install --pre pythonnet

```

--------------------------------

### Run Obsidianhtml Command

Source: https://obsidian-html.github.io/instructions/obsidianhtml-run.html

Use this command to quickly start a new website with ObsidianHtml. It requires the absolute path to your entry point note. Follow the on-screen instructions to launch a local webserver.

```bash
obsidianhtml run -f /absolute/path/to/your/entrypoint_note.md
```

--------------------------------

### Obsidian-HTML Search Result Example

Source: https://obsidian-html.github.io/demonstrations/embedded-search.html

This block shows the expected output after processing the 'query' code block example.

```text
convert automation webserver ssh

```

--------------------------------

### Ensure Pip Functionality

Source: https://obsidian-html.github.io/instructions/tutorials/specifics/bootstrapping-python-on-windows.html

Run the 'ensurepip' module to make the pip package installer functional. This is a necessary step before installing other Python packages.

```bash
C:\Users\User\Downloads\python-3.10.7\python.exe -m ensurepip
```

--------------------------------

### Run ObsidianHtml with Entrypoint Note

Source: https://obsidian-html.github.io/instructions/quickstart.html

Execute ObsidianHtml using the 'run' command, specifying an entrypoint note. This command converts the vault to HTML and hosts it locally.

```bash
obsidianhtml run -f /absolute/path/to/your/entrypoint_note.md

```

--------------------------------

### Install Specific Branch of ObsidianHtml

Source: https://obsidian-html.github.io/instructions/install-a-different-version.html

To install a specific branch, append '@branch_name' to the repository URL. This is useful for testing specific features or fixes.

```bash
pip uninstall obsidianhtml
pip install git+https://github.com/obsidian-html/obsidian-html.git@shutil_test
```

--------------------------------

### Configure Toggle Settings

Source: https://obsidian-html.github.io/configurations/configuration-options.html

Demonstrates the correct way to group toggle settings in the configuration file.

```yaml
# wrong
toggles:
  compile_md: True

toggles:
  compile_html: True
```

```yaml
# good
toggles:
  compile_md: True
  compile_html: True
```

```yaml
toggles:
  # Opt-in/-out of Obsidian->Md conversion, set to False when using proper markdown as input
  compile_md: True
```

--------------------------------

### Serve Local HTML Site

Source: https://obsidian-html.github.io/instructions/tutorials/tutorial-installation-on-windows.html

Execute this Python script to start a local web server on port 8000, using the 'output/html' folder as the webroot. This is suitable for local testing.

```python
python ./serve.py

```

--------------------------------

### Run Obsidian HTML with Default Configuration

Source: https://obsidian-html.github.io/instructions/obsidianhtml-run.html

Use this command to run obsidianhtml with default settings. It's recommended to use an absolute path for the entrypoint note. The command will automatically detect your vault, set up temporary output folders, compile the website, and start a local webserver.

```bash
obsidianhtml run -f /home/user/git/obsidian-html.github.io/__src/vault/ObsidianHtml.md
```

--------------------------------

### Install Virtualenv Package

Source: https://obsidian-html.github.io/instructions/tutorials/specifics/bootstrapping-python-on-windows.html

Use pip to install the 'virtualenv' package, which is required for creating isolated Python environments. This command assumes pip is functional after running 'ensurepip'.

```bash
C:\Users\User\Downloads\python-3.10.7\python.exe -m pip install virtualenv
```

--------------------------------

### Pass Options to Binary Module

Source: https://obsidian-html.github.io/configurations/modules/developer-documentation/running-a-binary-module.html

Demonstrates how to pass configuration options to a binary module using the `module_config` key. The binary module is responsible for retrieving these options.

```yaml
module_config:
  rust_example_module:
    b: "rust_example_module"

```

--------------------------------

### Full Custom Graph Template Example

Source: https://obsidian-html.github.io/configurations/styling/writing-a-custom-graph-view-template.html

This is a complete example of a custom graph template, including dependency loading, data fetching, and graph initialization with interactive features.

```javascript
// This function is called by obshtml when it wants to open the graph
function run(args) {
    if (window.ObsHtmlGraph.graph_dependencies_loaded['custom'] == false){
        // load the dependency and when done run initGraph(args)
        load_script_on_demand(
            '//unpkg.com/force-graph', initGraph, [args]
        )
        // tell obshtml that the dependencies have been loaded, so that they will not be loaded again a next time
        window.ObsHtmlGraph.graph_dependencies_loaded['custom'] = true;
    }
    else {
        // just run directly
        initGraph(args)
    }
}

function initGraph(args) {
    // open div right before loading the graph to avoid opening an empty div
    args.graph_container.style.display = "block";

    // Load data then start graph
    fetch(args.data).then(res => res.json()).then(data => {
        let g = window.ObsHtmlGraph.graphs[args.uid];

        // load starting node into global current_node_id
        g.current_node_id = args.current_node_id

        g.graph = ForceGraph()
            (args.graph_container)
            .graphData(data)
            .nodeLabel('id')
            .width(args.width)
            .height(args.height)
            .nodeColor((node) => {
                if (node.id == g.current_node_id){
                    return '#ff0000'
                }
                return '#546bdd'
             })
             .onNodeRightClick(node => {
                g.current_node_id = node.id;
            });
    });
}

// export the run() method so that it can be called by obshtml
export { 
    run
};

```

--------------------------------

### Define Obsidian Entrypoint Path

Source: https://obsidian-html.github.io/configurations/configuration-options.html

Specifies the note file to be used as the index.html. Must reside within the obsidian_folder_path_str.

```yaml
# The note that will be used as the index.html 
# should be in obsidian_folder_path_str
# Can be absent when toggles/compile_md == False
# Use full path or relative path, but don't use ~/
obsidian_entrypoint_path_str: '<REQUIRED_INPUT>'
```

--------------------------------

### Query Example for Embedded Search

Source: https://obsidian-html.github.io/demonstrations/embedded-search.html

This is an example of how to use the 'query' code block to embed search results within a note. Remove the leading dashes before the backticks to use it.

```markdown
-``` query
convert automation webserver ssh
-```
```

--------------------------------

### Automate website deployment on Linux

Source: https://obsidian-html.github.io/automation/automationlinuxgit.html

This script synchronizes a local Obsidian vault with a Git-tracked output directory, runs the ObsidianHtml conversion, and pushes the resulting static site to a remote repository.

```bash
# Config
git_output="/home/user/git/obsidian-html.github.io"
obsidian_folder="/home/user/git/obsidian-html"

# Move to output folder and make sure it is up to date
cd $git_output
git pull

# Remove all files except .git/ and README.md
echo "Will delete previous output:"
find . ! -path "./.git/*" ! -name ".git" ! -name README.md
echo "Continue? (y/n)"
read yn

if [ "$yn" != "y" ]; then
    echo "Aborted"
    exit 0
fi

find . ! -path "./.git/*" ! -name ".git" ! -name README.md -delete


# Convert Obsidian to HTML
cd $obsidian_folder
python -m obsidianhtml -i local_configs/example_site.yml
# ^ the config file will output the html to $git_output

if [ $? -ne 0 ]; then
    echo "Python script failed. Exited."
    exit 1
else
    echo "Successfully created html code"
fi

# Push changes
cd $git_output
mv html/* ./
rm -rf html/

git add . --all
git commit -m "autopush"
git push
```

--------------------------------

### Uninstall ObsidianHtml

Source: https://obsidian-html.github.io/instructions/installation.html

Removes the installed ObsidianHtml package from the environment.

```bash
pip uninstall obsidianhtml
```

--------------------------------

### Configure Input and Output Paths

Source: https://obsidian-html.github.io/instructions/usage.html

Define the markdown source directory, entry point file, and HTML output destination. Paths can be absolute or relative, but should not use the tilde (~) shorthand.

```yaml
# Input and output path of markdown files
# This can be an absolute or a relative path (relative to the working directory when calling obsidianhtml)
# Use full path or relative path, but don't use ~/
md_folder_path_str:  'C:/Users/<Username>/Documents/Website/md'

# Markdown entrypoint path
# This has to be md_folder_path_str + '/index.md' when toggles/compile_md == True
# This can be an absolute or a relative path (relative to the working directory when calling obsidianhtml)
# Use full path or relative path, but don't use ~/
md_entrypoint_path_str: 'C:/Users/<Username>/Documents/Website/md/index.md'

# Output path of HTML files
# This can be an absolute or a relative path (relative to the working directory when calling obsidianhtml)
# Use full path or relative path, but don't use ~/
html_output_folder_path_str: 'C:/Users/<Username>/Documents/Website/html'
```

--------------------------------

### Configure Output Paths

Source: https://obsidian-html.github.io/instructions/quickstart.html

Define input and output directories for markdown and HTML files in the configuration.

```yaml
# Input and output path of markdown files
# This can be an absolute or a relative path (relative to the working directory when calling obsidianhtml)
# Use full path or relative path, but don't use ~/
md_folder_path_str:  'C:/Users/Username/Documents/Website/md'

# Markdown entrypoint path
# This has to be md_folder_path_str + '/index.md' when toggles/compile_md == True
# This can be an absolute or a relative path (relative to the working directory when calling obsidianhtml)
# Use full path or relative path, but don't use ~/
md_entrypoint_path_str: 'C:/Users/Username/Documents/Website/md/index.md'

# Output path of HTML files
# This can be an absolute or a relative path (relative to the working directory when calling obsidianhtml)
# Use full path or relative path, but don't use ~/
html_output_folder_path_str: 'C:/Users/Username/Documents/Website/html'
```

--------------------------------

### Upgrade pip

Source: https://obsidian-html.github.io/instructions/installation.html

Ensures the pip package manager is up to date before installing dependencies.

```bash
pip install --upgrade pip
```
Tokens:
Raw