Add new identity reference docs (#1682)

Co-authored-by: Eike Haß <[email protected]>

config/articleRedirects.js

@@ -588,7 +588,7 @@ exports.articleRedirects = [
   },
   {
     from: '/identity.rs/libraries/wasm/api_reference/',
-    to: '/identity.rs/references/api/wasm/',
+    to: '/identity.rs/references/wasm/api_ref',
   },
   {
     from: '/identity.rs/libraries/wasm/getting_started/',

docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx

@@ -1,12 +1,12 @@
 # Verifiable Presentations
 
 A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./verifiable-credentials.mdx).
-It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for [validation](#validation).
+It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for validation.
 
-For instance: after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate,
+For instance, after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate,
 the holder stores it securely until asked to present it.
 A company could then request proof of that university degree: the holder can [create a verifiable presentation](./../how-tos/verifiable-credentials/create.mdx)
-containing their credential, which is already signed by their university, and present it to the company to [validate](./../how-tos/verifiable-credentials/create.mdx#validate-a-vc).
+containing their credential, already signed by their university, and present it to the company to [validate](./../how-tos/verifiable-credentials/create.mdx#validate-a-vc).
 
 Note that verifiable presentations that contain personal data should, as with verifiable credentials, be transmitted and stored securely off-chain to satisfy data privacy regulations such as [GDPR](https://gdpr.eu/).
 
@@ -20,7 +20,7 @@ See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/
 
 ### Replay Attacks
 
-A verifiable presentation without a challenge could potentially be stored by a malicious actor
+A malicious actor could potentially store a verifiable presentation without a challenge
 and replayed to a different verifier, impersonating the holder.
 This is because the holder's signature on a presentation would still be seen as valid indefinitely,
 until they [rotate](https://www.w3.org/TR/did-core/#verification-method-rotation) the verification method used.
@@ -35,5 +35,5 @@ The challenge string should be sufficiently random and unique for each verifiabl
 being predicted. 
 
 Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as
-per `JwtPresentationOptions`. However, verifiers and different implementations could choose to ignore that property,
+per `JwtPresentationOptions`. However, verifiers and different implementations could ignore that property,
 so setting a signature expiration alone should not be relied upon.

docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx

@@ -339,6 +339,6 @@ You may find it useful to see how the WASM bindings are being used in existing a
 
 - [Zebra IOTA Edge SDK](https://github.com/ZebraDevs/Zebra-Iota-Edge-SDK) (mobile apps using Capacitor.js + Svelte)
 
-## [API Reference](/identity.rs/references/api/wasm)
+## [API Reference](../references/api/wasm.mdx)
 
 ## [Examples](https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/README.md)

docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx

@@ -187,7 +187,7 @@ resolve the DID Documents of the [verifiable credential](./../../explanations/ve
 and presentation holder to verify their signatures.
 
 Resolving the necessary DID Documents is
-[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example)
+[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example-code)
 
 When direct access to these DID Documents is desired, the `Resolver` also provides standalone methods to:
 

docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx

@@ -21,7 +21,7 @@ while a service can provide metadata around the identity via URIs.
 
 ## Verification Methods
 
-As demonstrated by the [example](#example) below, the IOTA Identity framework offers easy-to-use methods for adding
+As demonstrated by the [example](#full-example-code) below, the IOTA Identity framework offers easy-to-use methods for adding
 [verification methods](https://www.w3.org/TR/did-core/#verification-methods).
 
 ### Properties

docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx

@@ -39,7 +39,7 @@ In the IOTA Identity Framework, you can create a Verifiable Credential with the
 
 
 
-## Signing {#signing}
+## Signing
 
 After preparing the verifiable credential, the issuer creates a signed JWT containing VC in the claims using one of their private keys. This is what allows verifiers to independently validate the credential using the corresponding public key from the issuer's DID Document.
 
@@ -71,7 +71,7 @@ and for enforcing [subject-holder relationships](https://www.w3.org/TR/vc-data-m
 
 ## Example
 
-The following code showcases how an issuer can [create, sign](#create-and-sign-vc),
+The following code showcases how an issuer can [create, sign](#create-and-sign-a-vc),
 and [validate](#validate-a-vc) a verifiable credential.
 In this example, the issuer signs a `UniversityDegreeCredential` with Alice's name and DID.
 

docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx

@@ -14,7 +14,7 @@ import TabItem from '@theme/TabItem';
 
 # Revoke a Verifiable Credential
 
-The [example](#example) below demonstrates two methods that an issuer can use to revoke a verifiable credential
+The [example](#full-example-code) below demonstrates two methods that an issuer can use to revoke a verifiable credential
 using the IOTA Identity Framework:
 
 1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking to a

docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx

@@ -188,7 +188,7 @@ Because of its space efficiency, a roaring bitmap is preferred for representing
 
 The [RevocationList2020 specification](https://w3c-ccg.github.io/vc-status-rl-2020/) and [StatusList2021 specification](https://w3c-ccg.github.io/vc-status-list-2021/) both describe a similar revocation mechanism using a verifiable credential that contains a bitmap, similar to the `RevocationBitmap2022` approach. The credential is hosted outside of the DID document and the verifier thus needs to fetch it from an external resource, likely one controlled by the issuer. This has privacy implications as the issuer can track where a fetch request for the credential came from and potentially infer who the credential was verified by and for what purpose. The issuer can also potentially infer which credential was checked. Because `RevocationBitmap2022` is embedded in the issuer's DID document, which can be obtained without the their knowledge, this approach does not suffer from these privacy shortcomings. See also the [privacy considerations](#privacy-considerations).
 
-A downside of embedding the revocation list in the DID document is that storage in a distributed ledger (DLT) is usually more expensive than other storage hosting solutions. The DLT might also impose message size limitations, capping the total number of revocations that can be done (see also [compression](#compression)).
+A downside of embedding the revocation list in the DID document is that storage in a distributed ledger (DLT) is usually more expensive than other storage hosting solutions. The DLT might also impose message size limitations, capping the total number of revocations that can be done (see also [compression](#compression-and-maximum-size)).
 
 Another difference is that `RevocationList2020` specifies a minimum initial size of 131,072 for its bitstring, to mitigate the potential for correlating individuals when few credentials have been issued. `RevocationBitmap2022` uses a roaring bitmap instead of a bitstring, so the maximum size is not fixed (apart from the upper bound of an unsigned 32-bit integer). This means the bitmap cannot be used to correlate small populations without more information not present in the bitmap itself. However, both schemes still reveal publicly how many credentials have been revoked, which could be used to infer other information if more knowledge about how an issuer assigns credential revocation indexes is known.
 

docs/build/identity.rs/1.0/docs/workflow.mdx

@@ -135,7 +135,7 @@ With the release process, we can deliver versions of our software to the communi
 
 The final list of changes from the [changelog](#changelog) informs the version of the release. If at least one change mapping to a major version is included, the major version needs to be incremented. In that case, the minor and patch versions are set to `0`. If there are no changes related to a major version, but changes related to a minor version are present, the minor version needs to be incremented while the patch version is set to `0`. Otherwise, only the patch version is incremented. Determining the version of the release is the responsibility of the person performing the release.
 
-The determined version of the release is used to create the [hotfix](#hotfix) or [release](#release) branch. For example, a major release from the previous version `v2.3.1` will create the `release/v3.0.0` branch.
+The determined version of the release is used to create the hotfix or [release](#release) branch. For example, a major release from the previous version `v2.3.1` will create the `release/v3.0.0` branch.
 
 Notice the `v` in front of the version. We [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) all release in git in the form of `vMAJOR.MINOR.PATCH`. For bindings, we prefix the tag with the binding name, so a tag for Wasm would look like `wasm-v1.2.3`. Bindings and the core Rust library are versioned and released independently.
 

docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx

@@ -1,7 +1,7 @@
 # Verifiable Presentations
 
 A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./verifiable-credentials.mdx).
-It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for [validation](#validation).
+It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for validation.
 
 For instance, after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate,
 the holder stores it securely until asked to present it.

docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx

@@ -334,6 +334,6 @@ You may find it useful to see how the WASM bindings are being used in existing a
 
 - [Zebra IOTA Edge SDK](https://github.com/ZebraDevs/Zebra-Iota-Edge-SDK) (mobile apps using Capacitor.js + Svelte)
 
-## [API Reference](/identity.rs/references/api/wasm)
+## [API Reference](../references/api/wasm.mdx)
 
 ## [Examples](https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/README.md)

docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx

@@ -187,7 +187,7 @@ resolve the DID Documents of the [verifiable credential](./../../explanations/ve
 and presentation holder to verify their signatures.
 
 Resolving the necessary DID Documents is
-[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example)
+[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example-code)
 
 When direct access to these DID Documents is desired, the `Resolver` also provides standalone methods to:
 

docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx

@@ -21,7 +21,7 @@ while a service can provide metadata around the identity via URIs.
 
 ## Verification Methods
 
-As demonstrated by the [example](#example) below, the IOTA Identity framework offers easy-to-use methods for adding
+As demonstrated by the [example](#full-example-code) below, the IOTA Identity framework offers easy-to-use methods for adding
 [verification methods](https://www.w3.org/TR/did-core/#verification-methods).
 
 ### Properties

docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx

@@ -39,7 +39,7 @@ In the IOTA Identity Framework, you can create a Verifiable Credential with the
 
 
 
-## Signing {#signing}
+## Signing
 
 After preparing the verifiable credential, the issuer creates a signed JWT containing VC in the claims using one of their private keys. This is what allows verifiers to validate the credential independently using the corresponding public key from the issuer's DID Document.
 
@@ -71,7 +71,7 @@ and for enforcing [subject-holder relationships](https://www.w3.org/TR/vc-data-m
 
 ## Example
 
-The following code showcases how an issuer can [create, sign](#create-and-sign-vc),
+The following code showcases how an issuer can [create, sign](#create-and-sign-a-vc),
 and [validate](#validate-a-vc) a verifiable credential.
 In this example, the issuer signs a `UniversityDegreeCredential` with Alice's name and DID.
 

docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx

@@ -14,7 +14,7 @@ import TabItem from '@theme/TabItem';
 
 # Revoke a Verifiable Credential
 
-The [example](#example) below demonstrates two methods that an issuer can use to revoke a verifiable credential
+The [example](#full-example-code) below demonstrates two methods that an issuer can use to revoke a verifiable credential
 using the IOTA Identity Framework:
 
 1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking

docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx

@@ -188,7 +188,7 @@ Because of its space efficiency, a roaring bitmap is preferred for representing
 
 The [RevocationList2020 specification](https://w3c-ccg.github.io/vc-status-rl-2020/) and [StatusList2021 specification](https://w3c-ccg.github.io/vc-status-list-2021/) both describe a similar revocation mechanism using a verifiable credential that contains a bitmap, similar to the `RevocationBitmap2022` approach. The credential is hosted outside of the DID document and the verifier thus needs to fetch it from an external resource, likely one controlled by the issuer. This has privacy implications as the issuer can track where a fetch request for the credential came from and potentially infer who the credential was verified by and for what purpose. The issuer can also potentially infer which credential was checked. Because `RevocationBitmap2022` is embedded in the issuer's DID document, which can be obtained without the their knowledge, this approach does not suffer from these privacy shortcomings. See also the [privacy considerations](#privacy-considerations).
 
-A downside of embedding the revocation list in the DID document is that storage in a distributed ledger (DLT) is usually more expensive than other storage hosting solutions. The DLT might also impose message size limitations, capping the total number of revocations that can be done (see also [compression](#compression)).
+A downside of embedding the revocation list in the DID document is that storage in a distributed ledger (DLT) is usually more expensive than other storage hosting solutions. The DLT might also impose message size limitations, capping the total number of revocations that can be done (see also [compression](#compression-and-maximum-size)).
 
 Another difference is that `RevocationList2020` specifies a minimum initial size of 131,072 for its bitstring, to mitigate the potential for correlating individuals when few credentials have been issued. `RevocationBitmap2022` uses a roaring bitmap instead of a bitstring, so the maximum size is not fixed (apart from the upper bound of an unsigned 32-bit integer). This means the bitmap cannot be used to correlate small populations without more information not present in the bitmap itself. However, both schemes still reveal publicly how many credentials have been revoked, which could be used to infer other information if more knowledge about how an issuer assigns credential revocation indexes is known.
 

docs/build/identity.rs/1.1/docs/workflow.mdx

@@ -135,7 +135,7 @@ With the release process, we can deliver versions of our software to the communi
 
 The final list of changes from the [changelog](#changelog) informs the version of the release. If at least one change mapping to a major version is included, the major version needs to be incremented. In that case, the minor and patch versions are set to `0`. If there are no changes related to a major version, but changes related to a minor version are present, the minor version needs to be incremented while the patch version is set to `0`. Otherwise, only the patch version is incremented. Determining the version of the release is the responsibility of the person performing the release.
 
-The determined version of the release is used to create the [hotfix](#hotfix) or [release](#release) branch. For example, a major release from the previous version `v2.3.1` will create the `release/v3.0.0` branch.
+The determined version of the release is used to create the hotfix or [release](#release) branch. For example, a major release from the previous version `v2.3.1` will create the `release/v3.0.0` branch.
 
 Notice the `v` in front of the version. We [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) all release in git in the form of `vMAJOR.MINOR.PATCH`. For bindings, we prefix the tag with the binding name, so a tag for Wasm would look like `wasm-v1.2.3`. Bindings and the core Rust library are versioned and released independently.
 

docs/build/identity.rs/1.2/docs/explanations/verifiable-presentations.mdx

@@ -1,7 +1,7 @@
 # Verifiable Presentations
 
 A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./verifiable-credentials.mdx).
-It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for [validation](#validation).
+It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for validation.
 
 For instance, after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate,
 the holder stores it securely until asked to present it.

docs/build/identity.rs/1.2/docs/getting-started/wasm.mdx

@@ -334,6 +334,6 @@ You may find it useful to see how the WASM bindings are being used in existing a
 
 - [Zebra IOTA Edge SDK](https://github.com/ZebraDevs/Zebra-Iota-Edge-SDK) (mobile apps using Capacitor.js + Svelte)
 
-## [API Reference](/identity.rs/references/api/wasm)
+## [API Reference](../references/api/wasm.mdx)
 
 ## [Examples](https://github.com/iotaledger/identity.rs/blob/v1.2.0/bindings/wasm/examples/README.md)

docs/build/identity.rs/1.2/docs/how-tos/decentralized-identifiers/resolve.mdx

@@ -187,7 +187,7 @@ resolve the DID Documents of the [verifiable credential](./../../explanations/ve
 and presentation holder to verify their signatures.
 
 Resolving the necessary DID Documents is
-[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example)
+[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example-code)
 
 When direct access to these DID Documents is desired, the `Resolver` also provides standalone methods to:
 

docs/build/identity.rs/1.2/docs/how-tos/decentralized-identifiers/update.mdx

@@ -21,7 +21,7 @@ while a service can provide metadata around the identity via URIs.
 
 ## Verification Methods
 
-As demonstrated by the [example](#example) below, the IOTA Identity framework offers easy-to-use methods for adding
+As demonstrated by the [example](#full-example-code) below, the IOTA Identity framework offers easy-to-use methods for adding
 [verification methods](https://www.w3.org/TR/did-core/#verification-methods).
 
 ### Properties

docs/build/identity.rs/1.2/docs/how-tos/verifiable-credentials/create.mdx

@@ -39,7 +39,7 @@ In the IOTA Identity Framework, you can create a Verifiable Credential with the
 
 
 
-## Signing {#signing}
+## Signing
 
 After preparing the verifiable credential, the issuer creates a signed JWT containing VC in the claims using one of their private keys. This is what allows verifiers to validate the credential independently using the corresponding public key from the issuer's DID Document.
 
@@ -71,7 +71,7 @@ and for enforcing [subject-holder relationships](https://www.w3.org/TR/vc-data-m
 
 ## Example
 
-The following code showcases how an issuer can [create, sign](#create-and-sign-vc),
+The following code showcases how an issuer can [create, sign](#create-and-sign-a-vc),
 and [validate](#validate-a-vc) a verifiable credential.
 In this example, the issuer signs a `UniversityDegreeCredential` with Alice's name and DID.