From 638e83e9dcd43062fb4a87b9f5a9a38298d16607 Mon Sep 17 00:00:00 2001 From: Nick Groenen Date: Sun, 11 Apr 2021 15:39:54 +0200 Subject: [PATCH] Simplify and improve documentation This removes mdBook in favor of a flat docs folder generating a single `README.md` in the repository root. Installation and usage instructions have also been expanded slightly. --- .pre-commit-config.yaml | 8 +- README.md | 324 ++++++++++++++++-- book/README.md | 3 - book/book-src/CHANGES.md | 231 ------------- book/book-src/Installation.md | 24 -- book/book-src/License.md | 3 - book/book-src/README.md | 112 ------ book/book-src/SUMMARY.md | 10 - book/book-src/Usage.md | 18 - book/book-src/index.md | 11 - book/book-src/installation.md | 17 - book/book-src/license.md | 3 - book/book-src/usage.md | 75 ---- book/book.toml | 9 - book/generate.sh | 9 - book/obsidian-src/CHANGES.md | 1 - book/obsidian-src/README.md | 4 - book/obsidian-src/SUMMARY.md | 10 - book/obsidian-src/installation.md | 18 - {book/obsidian-src => docs}/.obsidian/config | 0 docs/.obsidian/workspace | 110 ++++++ .../.obsidian/workspaces.json | 0 docs/CHANGES.md | 1 + .../Release-checklist.md | 4 +- docs/_combined.md | 8 + docs/_edit-warning.md | 13 + docs/generate.sh | 11 + docs/installation.md | 26 ++ book/obsidian-src/index.md => docs/intro.md | 5 +- {book/obsidian-src => docs}/license.md | 2 +- .../usage.md => docs/usage-advanced.md | 37 +- docs/usage-basic.md | 42 +++ docs/usage-library.md | 9 + 33 files changed, 538 insertions(+), 620 deletions(-) delete mode 100644 book/README.md delete mode 100644 book/book-src/CHANGES.md delete mode 100644 book/book-src/Installation.md delete mode 100644 book/book-src/License.md delete mode 100644 book/book-src/README.md delete mode 100644 book/book-src/SUMMARY.md delete mode 100644 book/book-src/Usage.md delete mode 100644 book/book-src/index.md delete mode 100644 book/book-src/installation.md delete mode 100644 book/book-src/license.md delete mode 100644 book/book-src/usage.md delete mode 100644 book/book.toml delete mode 100755 book/generate.sh delete mode 120000 book/obsidian-src/CHANGES.md delete mode 100644 book/obsidian-src/README.md delete mode 100644 book/obsidian-src/SUMMARY.md delete mode 100644 book/obsidian-src/installation.md rename {book/obsidian-src => docs}/.obsidian/config (100%) create mode 100644 docs/.obsidian/workspace rename {book/obsidian-src => docs}/.obsidian/workspaces.json (100%) create mode 120000 docs/CHANGES.md rename Release-checklist.md => docs/Release-checklist.md (80%) create mode 100644 docs/_combined.md create mode 100644 docs/_edit-warning.md create mode 100755 docs/generate.sh create mode 100644 docs/installation.md rename book/obsidian-src/index.md => docs/intro.md (70%) rename {book/obsidian-src => docs}/license.md (95%) rename book/obsidian-src/usage.md => docs/usage-advanced.md (59%) create mode 100644 docs/usage-basic.md create mode 100644 docs/usage-library.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f3e9ea0..d733744 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,8 +14,8 @@ repos: args: ["--", "-D", "warnings"] - repo: local hooks: - - id: mdbook - name: mdbook - entry: book/generate.sh + - id: README + name: Render README.md + entry: docs/generate.sh language: script - files: ^(README\.md)|(book/.*) + files: ^(README\.md)|(docs/.*) diff --git a/README.md b/README.md index 287621a..9c9bb3e 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,84 @@ + + + # Obsidian Export -*Rust library and associated CLI program to export an [Obsidian](https://obsidian.md/) vault to regular Markdown (specifically: [CommonMark](https://commonmark.org/))* +*Obsidian Export is a CLI program and a Rust library to export an [Obsidian](https://obsidian.md/) vault to regular Markdown.* -* Recursively export Obsidian Markdown files to CommonMark. +* Recursively export Obsidian Markdown files to [CommonMark](https://commonmark.org/). * Supports `[[note]]`-style references as well as `![[note]]` file includes. * Support for [gitignore](https://git-scm.com/docs/gitignore)-style exclude patterns (default: `.export-ignore`). * Automatically excludes files that are ignored by Git when the vault is located in a Git repository. +* Runs on all major platforms: Windows, Mac, Linux, BSDs. Please note obsidian-export is not officially endorsed by the Obsidian team. It supports most but not all of Obsidian's Markdown flavor. -## Installation +# Installation - > - > **Note**: - > *Obsidian-export* has been developed on Linux. - > Windows and Mac OS are covered as part of the continuous integration tests run on GitHub, but these have not been tested by the author. - > Experience reports from users on these operating systems would be welcomed. +## Pre-built binaries Binary releases for x86-64 processors are provided for Windows, Linux and Mac operating systems on a best-effort basis. -These may be downloaded from: [https://github.com/zoni/obsidian-export/releases](https://github.com/zoni/obsidian-export/releases) +They are built with GitHub runners as part of the release workflow defined in `.github/workflows/release.yml`. -Alternatively, *obsidian-export* may be compiled from source using [Cargo](https://doc.rust-lang.org/cargo/), the official package manager for Rust, by using the following steps: +The resulting binaries can be downloaded from [https://github.com/zoni/obsidian-export/releases](https://github.com/zoni/obsidian-export/releases) -1. Install the Rust toolchain: [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) +## Building from source + +When binary releases are unavailable for your platform, or you do not trust the pre-built binaries, then *obsidian-export* can be compiled from source with relatively little effort. +This is done through [Cargo](https://doc.rust-lang.org/cargo/), the official package manager for Rust, with the following steps: + +1. Install the Rust toolchain from [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) 1. Run: `cargo install obsidian-export` -The same `cargo install` command can later be used to upgrade to a newer release as well. + > + > It is expected that you successfully configured the PATH variable correctly while installing the Rust toolchain, as described under *"Configuring the PATH environment variable"* on [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install). + +## Upgrading from earlier versions + +If you downloaded a pre-built binary, upgrade by downloading the latest version to replace the old one. + +If you built from source, upgrade by running `cargo install obsidian-export` again. -## Usage +# Basic usage The main interface of *obsidian-export* is the `obsidian-export` CLI command. +As a text interface, this must be run from a terminal or Windows PowerShell. + +It is assumed that you have basic familiarity with command-line interfaces and that you set up your `PATH` correctly if you installed with `cargo`. +Running `obsidian-export --version` should print a version number rather than giving some kind of error. + + > + > If you downloaded a pre-built binary and didn't put it a location referenced by `PATH` (for example, you put it in `Downloads`), you will need to provide the full path to the binary instead. + > + > For example `~/Downloads/obsidian-export --version` on Mac/Linux or `~\Downloads\obsidian-export --version` on Windows (PowerShell). + In it's most basic form, `obsidian-export` takes just two mandatory arguments, a source and a destination: ````sh -obsidian-export my-obsidian-vault /tmp/export +obsidian-export /path/to/my-obsidian-vault /path/to/exported-notes/ ```` -This will export all of the files from `my-obsidian-vault` to `/tmp/export`, except for those listed in `.export-ignore` or `.gitignore`. +This will export all of the files from `my-obsidian-vault` to `exported-notes`, except for those listed in `.export-ignore` or `.gitignore`. + + > + > Note that the destination directory must exist, so you may need to create a new, empty directory first. + > + > If you give it an **existing** directory, files under that directory may get overwritten. It is also possible to export individual files: @@ -50,7 +89,7 @@ obsidian-export my-obsidian-vault/some-note.md /tmp/export/ obsidian-export my-obsidian-vault/some-note.md /tmp/exported-note.md ```` -### Character encodings +## Character encodings At present, UTF-8 character encoding is assumed for all note text as well as filenames. All text and file handling performs [lossy conversion to Unicode strings](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8_lossy). @@ -58,7 +97,10 @@ All text and file handling performs [lossy conversion to Unicode strings](https: Use of non-UTF8 encodings may lead to issues like incorrect text replacement and failure to find linked notes. While this may change in the future, there are no plans to change this behavior in the short term. -### Frontmatter + +# Advanced usage + +## Frontmatter By default, frontmatter is copied over "as-is". @@ -68,7 +110,7 @@ In these cases, `--frontmatter=always` can be used to insert an empty frontmatte To completely remove any frontmatter from exported notes, use `--frontmatter=never`. -### Ignoring files +## Ignoring files By default, hidden files, patterns listed in `.export-ignore` as well as any files ignored by git (if your vault is part of a git repository) will be excluded from exports. @@ -78,7 +120,7 @@ These options may be adjusted with `--hidden`, `--ignore-file` and `--no-git` if Notes linking to ignored notes will be unlinked (they'll only include the link text). Embeds of ignored notes will be skipped entirely. -#### Ignorefile syntax +### Ignorefile syntax The syntax for `.export-ignore` files is identical to that of [gitignore](https://git-scm.com/docs/gitignore) files. Here's an example: @@ -96,7 +138,7 @@ test For more comprehensive documentation and examples, see the [gitignore](https://git-scm.com/docs/gitignore) manpage. -### Recursive embeds +## Recursive embeds It's possible to end up with "recursive embeds" when two notes embed each other. This happens for example when a `Note A.md` contains `![[Note B]]` but `Note B.md` also contains `![[Note A]]`. @@ -107,6 +149,246 @@ This behavior may be changed by specifying `--no-recursive-embeds`. Using this mode, if a note is encountered for a second time while processing the original note, instead of embedding it again a link to the note is inserted instead to break the cycle. -## License +# Library usage + +All of the functionality exposed by the `obsidian-export` CLI command is also accessible as a Rust library, exposed through the [`obsidian_export` crate](https://crates.io/crates/obsidian-export). + +To get started, visit the library documentation on [obsidian_export](https://docs.rs/obsidian-export/latest/obsidian_export/) and [obsidian_export::Exporter](https://docs.rs/obsidian-export/latest/obsidian_export/struct.Exporter.html). + + +# License Obsidian-export is dual-licensed under the [Apache 2.0](https://github.com/zoni/obsidian-export/blob/master/LICENSE-APACHE) and the [MIT](https://github.com/zoni/obsidian-export/blob/master/LICENSE-MIT) licenses. + + +# Changelog + +## v0.6.0 (2021-02-15) + +### New + +* Add `--version` flag. \[Nick Groenen] + +### Changes + +* Don't Box FilterFn in WalkOptions. \[Nick Groenen] + + Previously, `filter_fn` on the `WalkOptions` struct looked like: + + ```` + pub filter_fn: Option>, + ```` + + This boxing was unneccesary and has been changed to: + + ```` + pub filter_fn: Option<&'static FilterFn>, + ```` + + This will only affect people who use obsidian-export as a library in + other Rust programs, not users of the CLI. + + For those library users, they no longer need to supply `FilterFn` + wrapped in a Box. + +### Fixes + +* Recognize notes beginning with underscores. \[Nick Groenen] + + Notes with an underscore would fail to be recognized within Obsidian + `[[_WikiLinks]]` due to the assumption that the underlying Markdown + parser (pulldown_cmark) would emit the text between `[[` and `]]` as + a single event. + + The note parser has now been rewritten to use a more reliable state + machine which correctly recognizes this corner-case (and likely some + others). + +* Support self-references. \[Joshua Coles] + + This ensures links to headings within the same note (`[[#Heading]]`) + resolve correctly. + +### Other + +* Avoid redundant "Release" in GitHub release titles. \[Nick Groenen] + +* Add failing testcase for files with underscores. \[Nick Groenen] + +* Add unit tests for display of ObsidianNoteReference. \[Nick Groenen] + +* Add some unit tests for ObsidianNoteReference::from_str. \[Nick Groenen] + +* Also run tests on pull requests. \[Nick Groenen] + +* Apply clippy suggestions following rust 1.50.0. \[Nick Groenen] + +* Fix infinite recursion bug with references to current file. \[Joshua Coles] + +* Add tests for self-references. \[Joshua Coles] + + Note as there is no support for block references at the moment, the generated link goes nowhere, however it is to a reasonable ID + +* Bump tempfile from 3.1.0 to 3.2.0. \[dependabot\[bot]] + + Bumps [tempfile](https://github.com/Stebalien/tempfile) from 3.1.0 to 3.2.0. + + * [Release notes](https://github.com/Stebalien/tempfile/releases) + * [Changelog](https://github.com/Stebalien/tempfile/blob/master/NEWS) + * [Commits](https://github.com/Stebalien/tempfile/commits) +* Bump eyre from 0.6.3 to 0.6.5. \[dependabot\[bot]] + + Bumps [eyre](https://github.com/yaahc/eyre) from 0.6.3 to 0.6.5. + + * [Release notes](https://github.com/yaahc/eyre/releases) + * [Changelog](https://github.com/yaahc/eyre/blob/v0.6.5/CHANGELOG.md) + * [Commits](https://github.com/yaahc/eyre/compare/v0.6.3...v0.6.5) +* Bump regex from 1.4.2 to 1.4.3. \[dependabot\[bot]] + + Bumps [regex](https://github.com/rust-lang/regex) from 1.4.2 to 1.4.3. + + * [Release notes](https://github.com/rust-lang/regex/releases) + * [Changelog](https://github.com/rust-lang/regex/blob/master/CHANGELOG.md) + * [Commits](https://github.com/rust-lang/regex/compare/1.4.2...1.4.3) + +## v0.5.1 (2021-01-10) + +### Fixes + +* Find uppercased notes when referenced with lowercase. \[Nick Groenen] + + This commit fixes a bug where, if a note contained uppercase characters + (for example `Note.md`) but was referred to using lowercase + (`[[note]]`), that note would not be found. + +## v0.5.0 (2021-01-05) + +### New + +* Add --no-recursive-embeds to break infinite recursion cycles. \[Nick Groenen] + + It's possible to end up with "recursive embeds" when two notes embed + each other. This happens for example when a `Note A.md` contains + `![[Note B]]` but `Note B.md` also contains `![[Note A]]`. + + By default, this will trigger an error and display the chain of notes + which caused the recursion. + + Using the new `--no-recursive-embeds`, if a note is encountered for a + second time while processing the original note, rather than embedding it + again a link to the note is inserted instead to break the cycle. + + See also: https://github.com/zoni/obsidian-export/issues/1 + +* Make walk options configurable on CLI. \[Nick Groenen] + + By default hidden files, patterns listed in `.export-ignore` as well as + any files ignored by git are excluded from exports. This behavior has + been made configurable on the CLI using the new flags `--hidden`, + `--ignore-file` and `--no-git`. + +* Support links referencing headings. \[Nick Groenen] + + Previously, links referencing a heading (`[[note#heading]]`) would just + link to the file name without including an anchor in the link target. + Now, such references will include an appropriate `#anchor` attribute. + + Note that neither the original Markdown specification, nor the more + recent CommonMark standard, specify how anchors should be constructed + for a given heading. + + There are also some differences between the various Markdown rendering + implementations. + + Obsidian-export uses the [slug](https://crates.io/crates/slug) crate to generate anchors which should + be compatible with most implementations, however your mileage may vary. + + (For example, GitHub may leave a trailing `-` on anchors when headings + end with a smiley. The slug library, and thus obsidian-export, will + avoid such dangling dashes). + +* Support embeds referencing headings. \[Nick Groenen] + + Previously, partial embeds (`![[note#heading]]`) would always include + the entire file into the source note. Now, such embeds will only include + the contents of the referenced heading (and any subheadings). + + Links and embeds of [arbitrary blocks](https://publish.obsidian.md/help/How+to/Link+to+blocks) remains unsupported at this time. + +### Changes + +* Print warnings to stderr rather than stdout. \[Nick Groenen] + + Warning messages emitted when encountering broken links/references will + now be printed to stderr as opposed to stdout. + +### Other + +* Include filter_fn field in WalkOptions debug display. \[Nick Groenen] + +## v0.4.0 (2020-12-23) + +### Fixes + +* Correct relative links within embedded notes. \[Nick Groenen] + + Links within an embedded note would point to other local resources + relative to the filesystem location of the note being embedded. + + When a note inside a different directory would embed such a note, these + links would point to invalid locations. + + Now these links are calculated relative to the top note, which ensures + these links will point to the right path. + +### Other + +* Add brief library documentation to all public types and functions. \[Nick Groenen] + +## v0.3.0 (2020-12-21) + +### New + +* Report file tree when RecursionLimitExceeded is hit. \[Nick Groenen] + + This refactors the Context to maintain a list of all the files which + have been processed so far in a chain of embeds. This information is + then used to print a more helpful error message to users of the CLI when + RecursionLimitExceeded is returned. + +### Changes + +* Add extra whitespace around multi-line warnings. \[Nick Groenen] + + This makes errors a bit easier to distinguish after a number of warnings + has been printed. + +### Other + +* Setup gitchangelog. \[Nick Groenen] + + This adds a changelog (CHANGES.md) which is automatically generated with + [gitchangelog](https://github.com/vaab/gitchangelog). + +## v0.2.0 (2020-12-13) + +* Allow custom filter function to be passed with WalkOptions. \[Nick Groenen] + +* Re-export vault_contents and WalkOptions as pub from crate root. \[Nick Groenen] + +* Run mdbook hook against README.md too. \[Nick Groenen] + +* Update installation instructions. \[Nick Groenen] + + Installation no longer requires a git repository URL now that a crate is + published. + +* Add MdBook generation script and precommit hook. \[Nick Groenen] + +* Add more reliable non-ASCII tetscase. \[Nick Groenen] + +* Create FUNDING.yml. \[Nick Groenen] + +## v0.1.0 (2020-11-28) + +* Public release. \[Nick Groenen] diff --git a/book/README.md b/book/README.md deleted file mode 100644 index 06cb0b6..0000000 --- a/book/README.md +++ /dev/null @@ -1,3 +0,0 @@ -This is an example of using obsidian-export to build documentation with the source stored as an Obsidian vault. - -The project level README.md is generated using this setup. diff --git a/book/book-src/CHANGES.md b/book/book-src/CHANGES.md deleted file mode 100644 index b3a522a..0000000 --- a/book/book-src/CHANGES.md +++ /dev/null @@ -1,231 +0,0 @@ -# Changelog - -## v0.6.0 (2021-02-15) - -### New - -* Add `--version` flag. \[Nick Groenen] - -### Changes - -* Don't Box FilterFn in WalkOptions. \[Nick Groenen] - - Previously, `filter_fn` on the `WalkOptions` struct looked like: - - ```` - pub filter_fn: Option>, - ```` - - This boxing was unneccesary and has been changed to: - - ```` - pub filter_fn: Option<&'static FilterFn>, - ```` - - This will only affect people who use obsidian-export as a library in - other Rust programs, not users of the CLI. - - For those library users, they no longer need to supply `FilterFn` - wrapped in a Box. - -### Fixes - -* Recognize notes beginning with underscores. \[Nick Groenen] - - Notes with an underscore would fail to be recognized within Obsidian - `[[_WikiLinks]]` due to the assumption that the underlying Markdown - parser (pulldown_cmark) would emit the text between `[[` and `]]` as - a single event. - - The note parser has now been rewritten to use a more reliable state - machine which correctly recognizes this corner-case (and likely some - others). - -* Support self-references. \[Joshua Coles] - - This ensures links to headings within the same note (`[[#Heading]]`) - resolve correctly. - -### Other - -* Avoid redundant "Release" in GitHub release titles. \[Nick Groenen] - -* Add failing testcase for files with underscores. \[Nick Groenen] - -* Add unit tests for display of ObsidianNoteReference. \[Nick Groenen] - -* Add some unit tests for ObsidianNoteReference::from_str. \[Nick Groenen] - -* Also run tests on pull requests. \[Nick Groenen] - -* Apply clippy suggestions following rust 1.50.0. \[Nick Groenen] - -* Fix infinite recursion bug with references to current file. \[Joshua Coles] - -* Add tests for self-references. \[Joshua Coles] - - Note as there is no support for block references at the moment, the generated link goes nowhere, however it is to a reasonable ID - -* Bump tempfile from 3.1.0 to 3.2.0. \[dependabot\[bot]] - - Bumps [tempfile](https://github.com/Stebalien/tempfile) from 3.1.0 to 3.2.0. - - * [Release notes](https://github.com/Stebalien/tempfile/releases) - * [Changelog](https://github.com/Stebalien/tempfile/blob/master/NEWS) - * [Commits](https://github.com/Stebalien/tempfile/commits) -* Bump eyre from 0.6.3 to 0.6.5. \[dependabot\[bot]] - - Bumps [eyre](https://github.com/yaahc/eyre) from 0.6.3 to 0.6.5. - - * [Release notes](https://github.com/yaahc/eyre/releases) - * [Changelog](https://github.com/yaahc/eyre/blob/v0.6.5/CHANGELOG.md) - * [Commits](https://github.com/yaahc/eyre/compare/v0.6.3...v0.6.5) -* Bump regex from 1.4.2 to 1.4.3. \[dependabot\[bot]] - - Bumps [regex](https://github.com/rust-lang/regex) from 1.4.2 to 1.4.3. - - * [Release notes](https://github.com/rust-lang/regex/releases) - * [Changelog](https://github.com/rust-lang/regex/blob/master/CHANGELOG.md) - * [Commits](https://github.com/rust-lang/regex/compare/1.4.2...1.4.3) - -## v0.5.1 (2021-01-10) - -### Fixes - -* Find uppercased notes when referenced with lowercase. \[Nick Groenen] - - This commit fixes a bug where, if a note contained uppercase characters - (for example `Note.md`) but was referred to using lowercase - (`[[note]]`), that note would not be found. - -## v0.5.0 (2021-01-05) - -### New - -* Add --no-recursive-embeds to break infinite recursion cycles. \[Nick Groenen] - - It's possible to end up with "recursive embeds" when two notes embed - each other. This happens for example when a `Note A.md` contains - `![[Note B]]` but `Note B.md` also contains `![[Note A]]`. - - By default, this will trigger an error and display the chain of notes - which caused the recursion. - - Using the new `--no-recursive-embeds`, if a note is encountered for a - second time while processing the original note, rather than embedding it - again a link to the note is inserted instead to break the cycle. - - See also: https://github.com/zoni/obsidian-export/issues/1 - -* Make walk options configurable on CLI. \[Nick Groenen] - - By default hidden files, patterns listed in `.export-ignore` as well as - any files ignored by git are excluded from exports. This behavior has - been made configurable on the CLI using the new flags `--hidden`, - `--ignore-file` and `--no-git`. - -* Support links referencing headings. \[Nick Groenen] - - Previously, links referencing a heading (`[[note#heading]]`) would just - link to the file name without including an anchor in the link target. - Now, such references will include an appropriate `#anchor` attribute. - - Note that neither the original Markdown specification, nor the more - recent CommonMark standard, specify how anchors should be constructed - for a given heading. - - There are also some differences between the various Markdown rendering - implementations. - - Obsidian-export uses the [slug](https://crates.io/crates/slug) crate to generate anchors which should - be compatible with most implementations, however your mileage may vary. - - (For example, GitHub may leave a trailing `-` on anchors when headings - end with a smiley. The slug library, and thus obsidian-export, will - avoid such dangling dashes). - -* Support embeds referencing headings. \[Nick Groenen] - - Previously, partial embeds (`![[note#heading]]`) would always include - the entire file into the source note. Now, such embeds will only include - the contents of the referenced heading (and any subheadings). - - Links and embeds of [arbitrary blocks](https://publish.obsidian.md/help/How+to/Link+to+blocks) remains unsupported at this time. - -### Changes - -* Print warnings to stderr rather than stdout. \[Nick Groenen] - - Warning messages emitted when encountering broken links/references will - now be printed to stderr as opposed to stdout. - -### Other - -* Include filter_fn field in WalkOptions debug display. \[Nick Groenen] - -## v0.4.0 (2020-12-23) - -### Fixes - -* Correct relative links within embedded notes. \[Nick Groenen] - - Links within an embedded note would point to other local resources - relative to the filesystem location of the note being embedded. - - When a note inside a different directory would embed such a note, these - links would point to invalid locations. - - Now these links are calculated relative to the top note, which ensures - these links will point to the right path. - -### Other - -* Add brief library documentation to all public types and functions. \[Nick Groenen] - -## v0.3.0 (2020-12-21) - -### New - -* Report file tree when RecursionLimitExceeded is hit. \[Nick Groenen] - - This refactors the Context to maintain a list of all the files which - have been processed so far in a chain of embeds. This information is - then used to print a more helpful error message to users of the CLI when - RecursionLimitExceeded is returned. - -### Changes - -* Add extra whitespace around multi-line warnings. \[Nick Groenen] - - This makes errors a bit easier to distinguish after a number of warnings - has been printed. - -### Other - -* Setup gitchangelog. \[Nick Groenen] - - This adds a changelog (CHANGES.md) which is automatically generated with - [gitchangelog](https://github.com/vaab/gitchangelog). - -## v0.2.0 (2020-12-13) - -* Allow custom filter function to be passed with WalkOptions. \[Nick Groenen] - -* Re-export vault_contents and WalkOptions as pub from crate root. \[Nick Groenen] - -* Run mdbook hook against README.md too. \[Nick Groenen] - -* Update installation instructions. \[Nick Groenen] - - Installation no longer requires a git repository URL now that a crate is - published. - -* Add MdBook generation script and precommit hook. \[Nick Groenen] - -* Add more reliable non-ASCII tetscase. \[Nick Groenen] - -* Create FUNDING.yml. \[Nick Groenen] - -## v0.1.0 (2020-11-28) - -* Public release. \[Nick Groenen] diff --git a/book/book-src/Installation.md b/book/book-src/Installation.md deleted file mode 100644 index b46b7b9..0000000 --- a/book/book-src/Installation.md +++ /dev/null @@ -1,24 +0,0 @@ -## Installation - -I don't currently provide binary releases, though I may create these if there is sufficient demand. -Until then, users can install *obsidian-export* from source using [Cargo](https://doc.rust-lang.org/cargo/): - -1. Install the Rust toolchain: [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) -1. Run: `cargo install https://github.com/zoni/obsidian-export.git --locked` - -The same `cargo install` command can be used to upgrade to a newer version as well. - -### Supported Operating Systems - -Obsidian-export has only been tested on GNU/Linux, but should run on any modern Unix-like system. - -Windows has not been tested and is unsupported at this time. -Experience reports from Windows users would be welcome however, and Windows support may be considered if the current UTF-8 filename assumption (see below) can hold true on Windows. - -### Character encodings - -At present, UTF-8 character encoding is assumed for all note text as well as filenames. -All text and file handling performs [lossy conversion to Unicode strings](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8_lossy). - -Use of non-UTF8 encodings may lead to issues like incorrect text replacement and failure to find linked notes. -While this may change in the future, there are no plans to change this behavior on the short term. diff --git a/book/book-src/License.md b/book/book-src/License.md deleted file mode 100644 index 5078806..0000000 --- a/book/book-src/License.md +++ /dev/null @@ -1,3 +0,0 @@ -## License - -Obsidian-export is dual-licensed under the [Apache 2.0](https://github.com/zoni/obsidian-export/blob/master/LICENSE-APACHE) and the [MIT](https://github.com/zoni/obsidian-export/blob/master/LICENSE-MIT) licenses. diff --git a/book/book-src/README.md b/book/book-src/README.md deleted file mode 100644 index 287621a..0000000 --- a/book/book-src/README.md +++ /dev/null @@ -1,112 +0,0 @@ -# Obsidian Export - -*Rust library and associated CLI program to export an [Obsidian](https://obsidian.md/) vault to regular Markdown (specifically: [CommonMark](https://commonmark.org/))* - -* Recursively export Obsidian Markdown files to CommonMark. -* Supports `[[note]]`-style references as well as `![[note]]` file includes. -* Support for [gitignore](https://git-scm.com/docs/gitignore)-style exclude patterns (default: `.export-ignore`). -* Automatically excludes files that are ignored by Git when the vault is located in a Git repository. - -Please note obsidian-export is not officially endorsed by the Obsidian team. -It supports most but not all of Obsidian's Markdown flavor. - - -## Installation - - > - > **Note**: - > *Obsidian-export* has been developed on Linux. - > Windows and Mac OS are covered as part of the continuous integration tests run on GitHub, but these have not been tested by the author. - > Experience reports from users on these operating systems would be welcomed. - -Binary releases for x86-64 processors are provided for Windows, Linux and Mac operating systems on a best-effort basis. -These may be downloaded from: [https://github.com/zoni/obsidian-export/releases](https://github.com/zoni/obsidian-export/releases) - -Alternatively, *obsidian-export* may be compiled from source using [Cargo](https://doc.rust-lang.org/cargo/), the official package manager for Rust, by using the following steps: - -1. Install the Rust toolchain: [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) -1. Run: `cargo install obsidian-export` - -The same `cargo install` command can later be used to upgrade to a newer release as well. - - -## Usage - -The main interface of *obsidian-export* is the `obsidian-export` CLI command. -In it's most basic form, `obsidian-export` takes just two mandatory arguments, a source and a destination: - -````sh -obsidian-export my-obsidian-vault /tmp/export -```` - -This will export all of the files from `my-obsidian-vault` to `/tmp/export`, except for those listed in `.export-ignore` or `.gitignore`. - -It is also possible to export individual files: - -````sh -# Export as some-note.md to /tmp/export/ -obsidian-export my-obsidian-vault/some-note.md /tmp/export/ -# Export as exported-note.md in /tmp/ -obsidian-export my-obsidian-vault/some-note.md /tmp/exported-note.md -```` - -### Character encodings - -At present, UTF-8 character encoding is assumed for all note text as well as filenames. -All text and file handling performs [lossy conversion to Unicode strings](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8_lossy). - -Use of non-UTF8 encodings may lead to issues like incorrect text replacement and failure to find linked notes. -While this may change in the future, there are no plans to change this behavior in the short term. - -### Frontmatter - -By default, frontmatter is copied over "as-is". - -Some static site generators are picky about frontmatter and require it to be present. -Some get tripped up when Markdown files don't have frontmatter but start with a list item or horizontal rule. -In these cases, `--frontmatter=always` can be used to insert an empty frontmatter entry. - -To completely remove any frontmatter from exported notes, use `--frontmatter=never`. - -### Ignoring files - -By default, hidden files, patterns listed in `.export-ignore` as well as any files ignored by git (if your vault is part of a git repository) will be excluded from exports. - -These options may be adjusted with `--hidden`, `--ignore-file` and `--no-git` if desired. -(See `--help` for more information). - -Notes linking to ignored notes will be unlinked (they'll only include the link text). -Embeds of ignored notes will be skipped entirely. - -#### Ignorefile syntax - -The syntax for `.export-ignore` files is identical to that of [gitignore](https://git-scm.com/docs/gitignore) files. -Here's an example: - -```` -# Ignore the directory private that is located at the top of the export tree -/private -# Ignore any file or directory called `test` -test -# Ignore any PDF file -*.pdf -# ..but include special.pdf -!special.pdf -```` - -For more comprehensive documentation and examples, see the [gitignore](https://git-scm.com/docs/gitignore) manpage. - -### Recursive embeds - -It's possible to end up with "recursive embeds" when two notes embed each other. -This happens for example when a `Note A.md` contains `![[Note B]]` but `Note B.md` also contains `![[Note A]]`. - -By default, this will trigger an error and display the chain of notes which caused the recursion. - -This behavior may be changed by specifying `--no-recursive-embeds`. -Using this mode, if a note is encountered for a second time while processing the original note, instead of embedding it again a link to the note is inserted instead to break the cycle. - - -## License - -Obsidian-export is dual-licensed under the [Apache 2.0](https://github.com/zoni/obsidian-export/blob/master/LICENSE-APACHE) and the [MIT](https://github.com/zoni/obsidian-export/blob/master/LICENSE-MIT) licenses. diff --git a/book/book-src/SUMMARY.md b/book/book-src/SUMMARY.md deleted file mode 100644 index 184d75d..0000000 --- a/book/book-src/SUMMARY.md +++ /dev/null @@ -1,10 +0,0 @@ -# Summary - -* [Introduction](index.md) -* [Installation](installation.md) -* [Usage](usage.md) - ---- - -[Changelog](CHANGES.md) -[License](license.md) diff --git a/book/book-src/Usage.md b/book/book-src/Usage.md deleted file mode 100644 index 0c598c5..0000000 --- a/book/book-src/Usage.md +++ /dev/null @@ -1,18 +0,0 @@ -## Usage - -The main interface of obsidian-export is the similarly-named `obsidian-export` CLI command. -In it's most basic form, `obsidian-export` takes just two mandatory arguments, source and destination: - -obsidian-export ~/Knowledgebase /tmp/export - -This will export all of the files from `~/Knowledgebase` to `/tmp/export`, except for those listed in `.export-ignore` or `.gitignore`. - -### Frontmatter - -By default, frontmatter is copied over "as-is". - -Some static site generators are picky about frontmatter and require it to be present. -Some get tripped up when Markdown files don't have frontmatter but start with a list item or horizontal rule. -In these cases, `--frontmatter=always` can be used to insert an empty frontmatter entry. - -To completely remove any frontmatter from exported notes, use `--frontmatter=never`. diff --git a/book/book-src/index.md b/book/book-src/index.md deleted file mode 100644 index a2110a0..0000000 --- a/book/book-src/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Obsidian Export - -*Rust library and associated CLI program to export an [Obsidian](https://obsidian.md/) vault to regular Markdown (specifically: [CommonMark](https://commonmark.org/))* - -* Recursively export Obsidian Markdown files to CommonMark. -* Supports `[[note]]`-style references as well as `![[note]]` file includes. -* Support for [gitignore](https://git-scm.com/docs/gitignore)-style exclude patterns (default: `.export-ignore`). -* Automatically excludes files that are ignored by Git when the vault is located in a Git repository. - -Please note obsidian-export is not officially endorsed by the Obsidian team. -It supports most but not all of Obsidian's Markdown flavor. diff --git a/book/book-src/installation.md b/book/book-src/installation.md deleted file mode 100644 index eacdf09..0000000 --- a/book/book-src/installation.md +++ /dev/null @@ -1,17 +0,0 @@ -## Installation - - > - > **Note**: - > *Obsidian-export* has been developed on Linux. - > Windows and Mac OS are covered as part of the continuous integration tests run on GitHub, but these have not been tested by the author. - > Experience reports from users on these operating systems would be welcomed. - -Binary releases for x86-64 processors are provided for Windows, Linux and Mac operating systems on a best-effort basis. -These may be downloaded from: [https://github.com/zoni/obsidian-export/releases](https://github.com/zoni/obsidian-export/releases) - -Alternatively, *obsidian-export* may be compiled from source using [Cargo](https://doc.rust-lang.org/cargo/), the official package manager for Rust, by using the following steps: - -1. Install the Rust toolchain: [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) -1. Run: `cargo install obsidian-export` - -The same `cargo install` command can later be used to upgrade to a newer release as well. diff --git a/book/book-src/license.md b/book/book-src/license.md deleted file mode 100644 index 5078806..0000000 --- a/book/book-src/license.md +++ /dev/null @@ -1,3 +0,0 @@ -## License - -Obsidian-export is dual-licensed under the [Apache 2.0](https://github.com/zoni/obsidian-export/blob/master/LICENSE-APACHE) and the [MIT](https://github.com/zoni/obsidian-export/blob/master/LICENSE-MIT) licenses. diff --git a/book/book-src/usage.md b/book/book-src/usage.md deleted file mode 100644 index e047cf4..0000000 --- a/book/book-src/usage.md +++ /dev/null @@ -1,75 +0,0 @@ -## Usage - -The main interface of *obsidian-export* is the `obsidian-export` CLI command. -In it's most basic form, `obsidian-export` takes just two mandatory arguments, a source and a destination: - -````sh -obsidian-export my-obsidian-vault /tmp/export -```` - -This will export all of the files from `my-obsidian-vault` to `/tmp/export`, except for those listed in `.export-ignore` or `.gitignore`. - -It is also possible to export individual files: - -````sh -# Export as some-note.md to /tmp/export/ -obsidian-export my-obsidian-vault/some-note.md /tmp/export/ -# Export as exported-note.md in /tmp/ -obsidian-export my-obsidian-vault/some-note.md /tmp/exported-note.md -```` - -### Character encodings - -At present, UTF-8 character encoding is assumed for all note text as well as filenames. -All text and file handling performs [lossy conversion to Unicode strings](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8_lossy). - -Use of non-UTF8 encodings may lead to issues like incorrect text replacement and failure to find linked notes. -While this may change in the future, there are no plans to change this behavior in the short term. - -### Frontmatter - -By default, frontmatter is copied over "as-is". - -Some static site generators are picky about frontmatter and require it to be present. -Some get tripped up when Markdown files don't have frontmatter but start with a list item or horizontal rule. -In these cases, `--frontmatter=always` can be used to insert an empty frontmatter entry. - -To completely remove any frontmatter from exported notes, use `--frontmatter=never`. - -### Ignoring files - -By default, hidden files, patterns listed in `.export-ignore` as well as any files ignored by git (if your vault is part of a git repository) will be excluded from exports. - -These options may be adjusted with `--hidden`, `--ignore-file` and `--no-git` if desired. -(See `--help` for more information). - -Notes linking to ignored notes will be unlinked (they'll only include the link text). -Embeds of ignored notes will be skipped entirely. - -#### Ignorefile syntax - -The syntax for `.export-ignore` files is identical to that of [gitignore](https://git-scm.com/docs/gitignore) files. -Here's an example: - -```` -# Ignore the directory private that is located at the top of the export tree -/private -# Ignore any file or directory called `test` -test -# Ignore any PDF file -*.pdf -# ..but include special.pdf -!special.pdf -```` - -For more comprehensive documentation and examples, see the [gitignore](https://git-scm.com/docs/gitignore) manpage. - -### Recursive embeds - -It's possible to end up with "recursive embeds" when two notes embed each other. -This happens for example when a `Note A.md` contains `![[Note B]]` but `Note B.md` also contains `![[Note A]]`. - -By default, this will trigger an error and display the chain of notes which caused the recursion. - -This behavior may be changed by specifying `--no-recursive-embeds`. -Using this mode, if a note is encountered for a second time while processing the original note, instead of embedding it again a link to the note is inserted instead to break the cycle. diff --git a/book/book.toml b/book/book.toml deleted file mode 100644 index 58b9a47..0000000 --- a/book/book.toml +++ /dev/null @@ -1,9 +0,0 @@ -[book] -authors = ["Nick Groenen"] -language = "en" -multilingual = false -src = "book-src" -title = "Obsidian Export" - -[output.html] -git-repository-url = "https://github.com/zoni/obsidian-export" diff --git a/book/generate.sh b/book/generate.sh deleted file mode 100755 index 1830018..0000000 --- a/book/generate.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/bin/sh - -set -euo pipefail - -cd "$(git rev-parse --show-toplevel)/book" - -cargo run obsidian-src book-src -mdbook build -cp book-src/README.md ../README.md diff --git a/book/obsidian-src/CHANGES.md b/book/obsidian-src/CHANGES.md deleted file mode 120000 index 8980b4a..0000000 --- a/book/obsidian-src/CHANGES.md +++ /dev/null @@ -1 +0,0 @@ -../../CHANGES.md \ No newline at end of file diff --git a/book/obsidian-src/README.md b/book/obsidian-src/README.md deleted file mode 100644 index a115b65..0000000 --- a/book/obsidian-src/README.md +++ /dev/null @@ -1,4 +0,0 @@ -![[index]] -![[installation]] -![[usage]] -![[license]] diff --git a/book/obsidian-src/SUMMARY.md b/book/obsidian-src/SUMMARY.md deleted file mode 100644 index 0af3125..0000000 --- a/book/obsidian-src/SUMMARY.md +++ /dev/null @@ -1,10 +0,0 @@ -# Summary - -- [[index|Introduction]] -- [[Installation]] -- [[Usage]] - ---- - -[[CHANGES|Changelog]] -[[License]] diff --git a/book/obsidian-src/installation.md b/book/obsidian-src/installation.md deleted file mode 100644 index ec17c87..0000000 --- a/book/obsidian-src/installation.md +++ /dev/null @@ -1,18 +0,0 @@ -## Installation - -> **Note**: -> _Obsidian-export_ has been developed on Linux. -> Windows and Mac OS are covered as part of the continuous integration tests run on GitHub, but these have not been tested by the author. -> Experience reports from users on these operating systems would be welcomed. - -Binary releases for x86-64 processors are provided for Windows, Linux and Mac operating systems on a best-effort basis. -These may be downloaded from: - -Alternatively, _obsidian-export_ may be compiled from source using [Cargo], the official package manager for Rust, by using the following steps: - -1. Install the Rust toolchain: -2. Run: `cargo install obsidian-export` - -The same `cargo install` command can later be used to upgrade to a newer release as well. - -[Cargo]: https://doc.rust-lang.org/cargo/ diff --git a/book/obsidian-src/.obsidian/config b/docs/.obsidian/config similarity index 100% rename from book/obsidian-src/.obsidian/config rename to docs/.obsidian/config diff --git a/docs/.obsidian/workspace b/docs/.obsidian/workspace new file mode 100644 index 0000000..775c383 --- /dev/null +++ b/docs/.obsidian/workspace @@ -0,0 +1,110 @@ +{ + "main": { + "id": "4f12c2ce3bf9c008", + "type": "split", + "children": [ + { + "id": "baf68d171a8d5faa", + "type": "leaf", + "active": true, + "state": { + "type": "markdown", + "state": { + "file": "usage.md", + "mode": "preview" + } + } + } + ], + "direction": "vertical" + }, + "left": { + "id": "a3c59e1a39a05e01", + "type": "split", + "children": [ + { + "id": "84a2d59cfa7a87d4", + "type": "tabs", + "children": [ + { + "id": "2fba2e464cd7bc76", + "type": "leaf", + "state": { + "type": "file-explorer", + "state": {} + } + }, + { + "id": "a39dbfd35009ee0a", + "type": "leaf", + "state": { + "type": "search", + "state": { + "query": "", + "matchingCase": false, + "explainSearch": false, + "collapseAll": false, + "extraContext": false, + "sortOrder": "alphabetical" + } + } + } + ] + } + ], + "direction": "horizontal", + "width": 300 + }, + "right": { + "id": "dd160adb1a186a62", + "type": "split", + "children": [ + { + "id": "1afb25294a9f458c", + "type": "tabs", + "children": [ + { + "id": "63636433504641d7", + "type": "leaf", + "state": { + "type": "backlink", + "state": { + "file": "usage.md", + "collapseAll": false, + "extraContext": false, + "sortOrder": "alphabetical", + "backlinkCollapsed": false, + "unlinkedCollapsed": true + } + } + }, + { + "id": "f08f9f179747649d", + "type": "leaf", + "state": { + "type": "outline", + "state": { + "file": "usage.md" + } + } + } + ] + } + ], + "direction": "horizontal", + "width": 300, + "collapsed": true + }, + "lastOpenFiles": [ + "usage.md", + "index.md", + "README.md", + "SUMMARY.md", + "CHANGES.md", + "installation.md", + "license.md", + "Installation.md", + "Usage.md", + "License.md" + ] +} \ No newline at end of file diff --git a/book/obsidian-src/.obsidian/workspaces.json b/docs/.obsidian/workspaces.json similarity index 100% rename from book/obsidian-src/.obsidian/workspaces.json rename to docs/.obsidian/workspaces.json diff --git a/docs/CHANGES.md b/docs/CHANGES.md new file mode 120000 index 0000000..cf54708 --- /dev/null +++ b/docs/CHANGES.md @@ -0,0 +1 @@ +../CHANGES.md \ No newline at end of file diff --git a/Release-checklist.md b/docs/Release-checklist.md similarity index 80% rename from Release-checklist.md rename to docs/Release-checklist.md index d633402..7c1242d 100644 --- a/Release-checklist.md +++ b/docs/Release-checklist.md @@ -5,8 +5,8 @@ - [ ] Commit changes to `Cargo.*` with the message format `Release vN.N.N` - [ ] Make git tag `vN.N.N` - [ ] Run `gitchangelog` -- [ ] Regenerate mdBook sources: `book/generate.sh` -- [ ] Stage `CHANGES.md` and `book/` and amend previous commit +- [ ] Regenerate README: `docs/generate.sh` +- [ ] Stage `CHANGES.md` and `docs/` and amend previous commit - [ ] Force update git tag `vN.N.N` - [ ] Push changes & tag - [ ] Wait for builds to turn green () diff --git a/docs/_combined.md b/docs/_combined.md new file mode 100644 index 0000000..267e6fc --- /dev/null +++ b/docs/_combined.md @@ -0,0 +1,8 @@ +![[_edit-warning]] +![[intro]] +![[installation]] +![[usage-basic]] +![[usage-advanced]] +![[usage-library]] +![[license]] +![[CHANGES]] diff --git a/docs/_edit-warning.md b/docs/_edit-warning.md new file mode 100644 index 0000000..c60d430 --- /dev/null +++ b/docs/_edit-warning.md @@ -0,0 +1,13 @@ + diff --git a/docs/generate.sh b/docs/generate.sh new file mode 100755 index 0000000..5cb0a02 --- /dev/null +++ b/docs/generate.sh @@ -0,0 +1,11 @@ +#!/bin/sh + +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +TMPDIR=$(mktemp -d) +trap 'rm -rf "$TMPDIR"' EXIT + +cargo run docs "$TMPDIR" +cp "${TMPDIR}/_combined.md" README.md diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..daf677b --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,26 @@ +# Installation + +## Pre-built binaries + +Binary releases for x86-64 processors are provided for Windows, Linux and Mac operating systems on a best-effort basis. +They are built with GitHub runners as part of the release workflow defined in `.github/workflows/release.yml`. + +The resulting binaries can be downloaded from + +## Building from source + +When binary releases are unavailable for your platform, or you do not trust the pre-built binaries, then _obsidian-export_ can be compiled from source with relatively little effort. +This is done through [Cargo], the official package manager for Rust, with the following steps: + +1. Install the Rust toolchain from +2. Run: `cargo install obsidian-export` + +> It is expected that you successfully configured the PATH variable correctly while installing the Rust toolchain, as described under _"Configuring the PATH environment variable"_ on . + +## Upgrading from earlier versions + +If you downloaded a pre-built binary, upgrade by downloading the latest version to replace the old one. + +If you built from source, upgrade by running `cargo install obsidian-export` again. + +[Cargo]: https://doc.rust-lang.org/cargo/ diff --git a/book/obsidian-src/index.md b/docs/intro.md similarity index 70% rename from book/obsidian-src/index.md rename to docs/intro.md index 58841c1..a975c3c 100644 --- a/book/obsidian-src/index.md +++ b/docs/intro.md @@ -1,11 +1,12 @@ # Obsidian Export -_Rust library and associated CLI program to export an [Obsidian] vault to regular Markdown (specifically: [CommonMark])_ +_Obsidian Export is a CLI program and a Rust library to export an [Obsidian] vault to regular Markdown._ -- Recursively export Obsidian Markdown files to CommonMark. +- Recursively export Obsidian Markdown files to [CommonMark]. - Supports `[[note]]`-style references as well as `![[note]]` file includes. - Support for [gitignore]-style exclude patterns (default: `.export-ignore`). - Automatically excludes files that are ignored by Git when the vault is located in a Git repository. +- Runs on all major platforms: Windows, Mac, Linux, BSDs. Please note obsidian-export is not officially endorsed by the Obsidian team. It supports most but not all of Obsidian's Markdown flavor. diff --git a/book/obsidian-src/license.md b/docs/license.md similarity index 95% rename from book/obsidian-src/license.md rename to docs/license.md index 9f2f923..cdde289 100644 --- a/book/obsidian-src/license.md +++ b/docs/license.md @@ -1,4 +1,4 @@ -## License +# License Obsidian-export is dual-licensed under the [Apache 2.0] and the [MIT] licenses. diff --git a/book/obsidian-src/usage.md b/docs/usage-advanced.md similarity index 59% rename from book/obsidian-src/usage.md rename to docs/usage-advanced.md index d94582c..7dc7e14 100644 --- a/book/obsidian-src/usage.md +++ b/docs/usage-advanced.md @@ -1,32 +1,6 @@ -## Usage +# Advanced usage -The main interface of _obsidian-export_ is the `obsidian-export` CLI command. -In it's most basic form, `obsidian-export` takes just two mandatory arguments, a source and a destination: - -```sh -obsidian-export my-obsidian-vault /tmp/export -``` - -This will export all of the files from `my-obsidian-vault` to `/tmp/export`, except for those listed in `.export-ignore` or `.gitignore`. - -It is also possible to export individual files: - -```sh -# Export as some-note.md to /tmp/export/ -obsidian-export my-obsidian-vault/some-note.md /tmp/export/ -# Export as exported-note.md in /tmp/ -obsidian-export my-obsidian-vault/some-note.md /tmp/exported-note.md -``` - -### Character encodings - -At present, UTF-8 character encoding is assumed for all note text as well as filenames. -All text and file handling performs [lossy conversion to Unicode strings][from_utf8_lossy]. - -Use of non-UTF8 encodings may lead to issues like incorrect text replacement and failure to find linked notes. -While this may change in the future, there are no plans to change this behavior in the short term. - -### Frontmatter +## Frontmatter By default, frontmatter is copied over "as-is". @@ -36,7 +10,7 @@ In these cases, `--frontmatter=always` can be used to insert an empty frontmatte To completely remove any frontmatter from exported notes, use `--frontmatter=never`. -### Ignoring files +## Ignoring files By default, hidden files, patterns listed in `.export-ignore` as well as any files ignored by git (if your vault is part of a git repository) will be excluded from exports. @@ -46,7 +20,7 @@ These options may be adjusted with `--hidden`, `--ignore-file` and `--no-git` if Notes linking to ignored notes will be unlinked (they'll only include the link text). Embeds of ignored notes will be skipped entirely. -#### Ignorefile syntax +### Ignorefile syntax The syntax for `.export-ignore` files is identical to that of [gitignore] files. Here's an example: @@ -64,7 +38,7 @@ test For more comprehensive documentation and examples, see the [gitignore] manpage. -### Recursive embeds +## Recursive embeds It's possible to end up with "recursive embeds" when two notes embed each other. This happens for example when a `Note A.md` contains `![[Note B]]` but `Note B.md` also contains `![[Note A]]`. @@ -74,5 +48,4 @@ By default, this will trigger an error and display the chain of notes which caus This behavior may be changed by specifying `--no-recursive-embeds`. Using this mode, if a note is encountered for a second time while processing the original note, instead of embedding it again a link to the note is inserted instead to break the cycle. -[from_utf8_lossy]: https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8_lossy [gitignore]: https://git-scm.com/docs/gitignore diff --git a/docs/usage-basic.md b/docs/usage-basic.md new file mode 100644 index 0000000..f14847e --- /dev/null +++ b/docs/usage-basic.md @@ -0,0 +1,42 @@ +# Basic usage + +The main interface of _obsidian-export_ is the `obsidian-export` CLI command. +As a text interface, this must be run from a terminal or Windows PowerShell. + +It is assumed that you have basic familiarity with command-line interfaces and that you set up your `PATH` correctly if you installed with `cargo`. +Running `obsidian-export --version` should print a version number rather than giving some kind of error. + +> If you downloaded a pre-built binary and didn't put it a location referenced by `PATH` (for example, you put it in `Downloads`), you will need to provide the full path to the binary instead. +> +> For example `~/Downloads/obsidian-export --version` on Mac/Linux or `~\Downloads\obsidian-export --version` on Windows (PowerShell). + +In it's most basic form, `obsidian-export` takes just two mandatory arguments, a source and a destination: + +```sh +obsidian-export /path/to/my-obsidian-vault /path/to/exported-notes/ +``` + +This will export all of the files from `my-obsidian-vault` to `exported-notes`, except for those listed in `.export-ignore` or `.gitignore`. + +> Note that the destination directory must exist, so you may need to create a new, empty directory first. +> +> If you give it an **existing** directory, files under that directory may get overwritten. + +It is also possible to export individual files: + +```sh +# Export as some-note.md to /tmp/export/ +obsidian-export my-obsidian-vault/some-note.md /tmp/export/ +# Export as exported-note.md in /tmp/ +obsidian-export my-obsidian-vault/some-note.md /tmp/exported-note.md +``` + +## Character encodings + +At present, UTF-8 character encoding is assumed for all note text as well as filenames. +All text and file handling performs [lossy conversion to Unicode strings][from_utf8_lossy]. + +Use of non-UTF8 encodings may lead to issues like incorrect text replacement and failure to find linked notes. +While this may change in the future, there are no plans to change this behavior in the short term. + +[from_utf8_lossy]: https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8_lossy diff --git a/docs/usage-library.md b/docs/usage-library.md new file mode 100644 index 0000000..148431b --- /dev/null +++ b/docs/usage-library.md @@ -0,0 +1,9 @@ +# Library usage + +All of the functionality exposed by the `obsidian-export` CLI command is also accessible as a Rust library, exposed through the [`obsidian_export` crate][obsidian-export-crates-io]. + +To get started, visit the library documentation on [obsidian_export][crate-docs] and [obsidian_export::Exporter][exporter-docs]. + +[obsidian-export-crates-io]: https://crates.io/crates/obsidian-export +[crate-docs]: https://docs.rs/obsidian-export/latest/obsidian_export/ +[exporter-docs]: https://docs.rs/obsidian-export/latest/obsidian_export/struct.Exporter.html