frontammter: bump release version

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Version 3.1.0
+
+Added frontmatter feature:
+
+- `doc_location` keyword allows to externalize documentation.
+
+See our [full specification](./doc/frontmatter.md).
+
+by @hsjobeki;
+
+in https://github.com/nix-community/nixdoc/pull/114.
+
 ## Version 3.0.2
 
 Avoid displaying arguments when a doc-comment is already in place.

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "nixdoc"
-version = "3.0.2"
-authors = ["Vincent Ambo <mail@tazj.in>", "asymmetric"]
+version = "3.1.0"
+authors = ["Vincent Ambo <mail@tazj.in>", "asymmetric", "hsjobeki"]
 edition = "2021"
 description = "Generate CommonMark from Nix library functions"
 

README.md

@@ -18,17 +18,20 @@ It is important to start doc-comments with the additional asterisk (`*`) -> `/**
 
 The content of the doc-comment should conform to the [Commonmark](https://spec.commonmark.org/0.30/) specification.
 
-### Example
+### Examples
+
+#### Example: simple but complete example
 
 The following is an example of markdown documentation for new and current users of nixdoc.
 
-> Sidenote: Indentation is automatically detected and should be consistent across the content. 
-> 
+> Sidenote: Indentation is automatically detected and should be consistent across the content.
+>
 > If you are used to multiline-strings (`''`) in nix this should be intuitive to follow.
 
+`simple.nix`
 ````nix
 {
-  /** 
+  /**
     This function adds two numbers
 
     # Example
@@ -60,10 +63,39 @@ The following is an example of markdown documentation for new and current users
 
 > Note: Within nixpkgs the convention of using [definition-lists](https://www.markdownguide.org/extended-syntax/#definition-lists) for documenting arguments has been established.
 
+## Example: using frontmatter
+
+In some cases, it may be desirable to store the documentation in a separate Markdown file.
+Nixdoc supports frontmatter, which allows a separate Markdown file to be referenced within the doc comment.
+
+`fontmatter.nix`
+````nix
+{
+  /**
+    ---
+    doc_location: ./docs.md
+    ---
+  */
+  add = a: b: a + b;
+}
+````
+
+`./docs.md`
+````markdown
+# Add
+
+A simple function that adds two numbers.
+````
+
+> Note: Frontmatter works only with the newer doc-comments `/** */`.
+
+See our [frontmatter specification](./doc/frontmatter.md) for further information.
+
+## Legacy support
 
-## Custom nixdoc format (Legacy)
+### Custom nixdoc format
 
-You should consider migrating to the newer format described above.
+You should consider migrating to the newer format described above. The format described in this section will be removed with the next major release.
 
 See [Migration guide](./doc/migration.md).
 

doc/frontmatter.md

@@ -78,15 +78,16 @@ some nice docs!
 In this example, the `doc_location` directive fetches content from `./path.md` treating it as if it were directly within the doc-comment.
 This allows tracking the reference between the source position and the markdown file, in case of external documentation.
 
-## Extensibility
+## Error handling
 
-The initial set of keywords is intentionally minimalistic, focusing on immediate and broadly applicable needs.
+Any issues encountered during the processing of frontmatter — be it syntax errors, invalid paths, or unsupported keywords—should result in clear, actionable error messages to the user.
 
-Community contributions are encouraged to expand this list as new use cases emerge.
+## Extensibility
 
-## Error handling
+The initial set of keywords is intentionally minimalistic, focusing on immediate and broadly applicable needs.
 
-Any issues encountered during the processing of frontmatter—be it syntax errors, invalid paths, or unsupported keywords—should result in clear, actionable error messages to the user.
+When extending this document we ask our contributors to be tooling agnostic, such that documentation wont't rely on any implementation details.
+This approach ensures that the documentation remains independent of specific implementation details. By adhering to this principle, we aim to create a resource that is universally applicable
 
 ## Future work