Simplify docs structure (#81)

* Updated the docs sctructure

* Updated homepage

* Added internal link validator

* Updated links

* Updated anchor builder

* Fixed linting

astro.config.js

@@ -4,6 +4,8 @@ import { defineConfig } from "astro/config"
 import rehypeAutolinkHeadings from "rehype-autolink-headings"
 import { remarkHeadingId } from "remark-custom-heading-id"
 
+// import starlightLinksValidator from "starlight-links-validator"
+
 // https://astro.build/config
 export default defineConfig({
   site: "https://datapackage.org",
@@ -28,12 +30,11 @@ export default defineConfig({
       lastUpdated: true,
       customCss: ["/assets/styles.css"],
       tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 5 },
+      // The link validator is useful for debugging but it cleates a lot of false positives
+      // plugins: [starlightLinksValidator()],
       sidebar: [
+        { label: "Overview", autogenerate: { directory: "overview" } },
         { label: "Standard", autogenerate: { directory: "standard" } },
-        {
-          label: "Specifications",
-          autogenerate: { directory: "specifications" },
-        },
         {
           label: "Extensions",
           collapsed: true,

content/docs/guides/using-data-package.md

@@ -7,7 +7,7 @@ sidebar:
 There are many alternatives when it comes to Data Package Standard implementations. We will cover a few the most popular options which will be a good starting point.
 
 :::tip
-Please take a look at the full list of Data Package [Software](../../standard/software/) to find other implementations.
+Please take a look at the full list of Data Package [Software](/overview/software/) to find other implementations.
 :::
 
 ## Open Data Editor

content/docs/index.mdx

@@ -16,11 +16,11 @@ hero:
     alt: Data Packages Illustration
   actions:
     - text: Get Started
-      link: /standard/introduction/
+      link: /overview/introduction/
       icon: right-arrow
       variant: primary
     - text: Use Cases
-      link: /standard/adoption/
+      link: /overview/adoption/
       icon: rocket
       variant: secondary
     - text: View on GitHub
@@ -41,30 +41,22 @@ import { CardGrid, LinkCard, Card } from "@astrojs/starlight/components"
 
 <h2>Standard</h2>
 
-The Data Package standard is a comprehensive set of **specifications** that collectively define a framework for organizing, documenting, and sharing data in a structured and interoperable manner -- [EXPLORE THE STANDARD](/standard/specifications)
+The Data Package standard is a comprehensive set of **specifications** that collectively define a framework for organizing, documenting, and sharing data in a structured and interoperable manner -- [EXPLORE THE STANDARD](/standard/data-package)
 
 <CardGrid>
-  <ClickableCard
-    title="Data Package"
-    icon="open-book"
-    href="/specifications/data-package"
-  >
+  <ClickableCard title="Data Package" icon="open-book" href="/standard/data-package">
     A simple container format to describe a coherent collection of data (a dataset),
     including its contributors, licenses, etc.
   </ClickableCard>
-  <ClickableCard title="Data Resource" icon="rocket" href="/specifications/data-resource">
+  <ClickableCard title="Data Resource" icon="rocket" href="/standard/data-resource">
     A simple format to describe a data resource such as a individual table or file,
     including its name, format, path, etc.
   </ClickableCard>
-  <ClickableCard
-    title="Table Dialect"
-    icon="document"
-    href="/specifications/table-dialect"
-  >
+  <ClickableCard title="Table Dialect" icon="document" href="/standard/table-dialect">
     A simple format to describe the dialect of a tabular data file, including its
     delimiter, header rows, escape characters, etc.
   </ClickableCard>
-  <ClickableCard title="Table Schema" icon="puzzle" href="/specifications/table-schema">
+  <ClickableCard title="Table Schema" icon="puzzle" href="/standard/table-schema">
     A simple format to describe tabular data, including field names, types, constraints,
     missing values, foreign keys, etc.
   </ClickableCard>
@@ -74,15 +66,15 @@ The Data Package standard is a comprehensive set of **specifications** that coll
 
 <h2>Software</h2>
 
-Data Package is backed by a suite of software tools supporting the standard. From the no-code visual tool **Open Data Editor** to low-level drivers for 10 programming languages -- [EXPLORE THE SOFTWARE](/standard/software)
+Data Package is backed by a suite of software tools supporting the standard. From the no-code visual tool **Open Data Editor** to low-level drivers for 10 programming languages -- [EXPLORE THE SOFTWARE](/overview/software)
 
 [![Open Data Editor](../../assets/software/ode.png)](https://opendataeditor.okfn.org)
 
 <div style="margin-bottom: 5em"></div>
 
 <h2>Adoption</h2>
 
-Data Package is used for a wide range of scenarios where this standardized data packaging format proves invaluable for efficient data management, sharing, and analysis -- [EXPLORE THE ADOPTION](/standard/adoption)
+Data Package is used for a wide range of scenarios where this standardized data packaging format proves invaluable for efficient data management, sharing, and analysis -- [EXPLORE THE ADOPTION](/overview/adoption)
 
 <Adoption />
 
@@ -93,10 +85,10 @@ Data Package is used for a wide range of scenarios where this standardized data
 Read the Data Package documentation to learn more about the standard:
 
 <CardGrid>
-  <LinkCard title="Specifications" href="/standard/specifications" />
-  <LinkCard title="Extensions" href="/standard/extensions" />
-  <LinkCard title="Recipes" href="/standard/recipes" />
-  <LinkCard title="Guides" href="/standard/guides" />
+  <LinkCard title="Standard" href="/standard/data-package" />
+  <LinkCard title="Extensions" href="/extensions/camtrap-data-package" />
+  <LinkCard title="Recipes" href="/recipes/caching-of-resources" />
+  <LinkCard title="Guides" href="/guides/using-data-package" />
 </CardGrid>
 
 <About title="Brought to you by">

content/docs/overview/changelog.md

@@ -0,0 +1,126 @@
+---
+title: Changelog
+sidebar:
+  order: 10
+---
+
+This document includes all meaningful changes made to the Data Package Standard **specifications**. It does not cover changes made to other documents like Recipes or Guides.
+
+## v2.0-draft
+
+> April 1, 2024
+
+### Overview
+
+The Data Package (v2) draft release includes a rich set of the specification improvements accepted by the Data Package Working Group during the active phase of the Data Package (v2) work.
+
+### Data Package
+
+##### `version` (updated)
+
+[`version`](/standard/data-package/#version) is now included in the specification, while in Data Package v1 it was erroneously only part of the documentation ([#3](https://github.com/frictionlessdata/datapackage/pull/3)).
+
+##### `contributors` (updated)
+
+[`contributors`](/standard/data-package/#contributors) was updated:
+
+- `contributor.title` is no longer required ([#7](https://github.com/frictionlessdata/datapackage/pull/7)).
+- `contributor.givenName` and `contributor.familyName` are new properties to specify the given and family name of contributor, if it is a person ([#20](https://github.com/frictionlessdata/datapackage/pull/20)).
+- `contributor.role` has been deprecated in favour of `contributor.roles`, see further ([#18](https://github.com/frictionlessdata/datapackage/pull/18)).
+- `contributor.roles` is a new property that allows to specify multiple roles per contributor, rather than having to duplicate the contributor. It recommendeds to follow an established vocabulary and has suggested values that are different from the deprecated `contributor.role` ([#18](https://github.com/frictionlessdata/datapackage/pull/18)).
+
+##### `sources` (updated)
+
+[`sources`](/standard/data-package/#sources) was updated:
+
+- `source.title` is no longer required ([#7](https://github.com/frictionlessdata/datapackage/pull/7)).
+- `source.version` is a new property to specify which version of a source was used ([#10](https://github.com/frictionlessdata/datapackage/pull/10)).
+
+### Data Resource
+
+##### `name` (updated)
+
+[name](/standard/data-resource/#name-required) now allows any string. It previously required the name to only consist of lowercase alphanumeric characters plus `.`, `-` and `_`. The property is still required and must be unique among resources ([#27](https://github.com/frictionlessdata/datapackage/pull/27)).
+
+##### `path` (updated)
+
+[path](/standard/data-resource/#path-or-data-required) now explicitely forbids hidden folders (starting with dot `.`) ([#19](https://github.com/frictionlessdata/datapackage/pull/19)).
+
+##### `encoding` (updated)
+
+[encoding](/standard/data-resource/#encoding)'s definition has been updated to support binary formats like Parquet ([#15](https://github.com/frictionlessdata/datapackage/pull/15)).
+
+### Table Dialect
+
+[Table Dialect](/standard/table-dialect) is a new specification that superseeds and extends the CSV Dialect specification. It support other formats like JSON or Excel ([#41](https://github.com/frictionlessdata/datapackage/pull/41)).
+
+### Table Schema
+
+#### Schema
+
+##### `fieldsMatch` (new)
+
+[fieldsMatch](/standard/table-schema/#fieldsmatch) allows to specify how fields in a Table Schema match the fields in the data source. The default (`exact`) matches the Data Package v1 behaviour, but other values (e.g. `subset`, `superset`) allow to define fewer or more fields and match on field names. This new property extends and makes explicit the `schema_sync` option in Frictionless Framework ([#39](https://github.com/frictionlessdata/datapackage/pull/39)).
+
+##### `primaryKey` (updated)
+
+[`primaryKey`](/standard/table-schema/#primarykey) should now always be an array of strings, not a string ([#28](https://github.com/frictionlessdata/datapackage/pull/28)).
+
+##### `uniqueKeys` (new)
+
+[`uniqueKeys`](/standard/table-schema/#uniquekeys) allows to specify which fields are required to have unique logical values. It is an alternative to `field.contraints.unique` and is modelled after the corresponding SQL feature ([#30](https://github.com/frictionlessdata/datapackage/pull/30)).
+
+##### `foreignKeys` (updated)
+
+[`foreignKeys`](/standard/table-schema/#foreignkeys) was updated:
+
+- It should now always be an array of strings, not a string ([#28](https://github.com/frictionlessdata/datapackage/pull/28)).
+- `foreignKeys.reference.resource` can now be omitted for self-referencing foreign keys. Previously it required setting `resource` to an empty string ([#29](https://github.com/frictionlessdata/datapackage/pull/29)).
+
+#### Fields
+
+##### `missingValues` (new)
+
+[`missingValues`](/standard/table-schema/#missingvalues) allows to specify missing values per field, and overwrites `missingValues` specified at a resource level ([#24](https://github.com/frictionlessdata/datapackage/pull/24)).
+
+#### Field Types
+
+##### `integer` (updated)
+
+[`integer`](/standard/table-schema/#integer) now has a `groupChar` property. It was already available for `number` ([#6](https://github.com/frictionlessdata/datapackage/pull/6)).
+
+##### `list` (new)
+
+[`list`](/standard/table-schema/#list) allows to specify fields containing collections of primary values separated by a delimiter (e.g. `value1,value2`) ([#38](https://github.com/frictionlessdata/datapackage/pull/38)).
+
+##### `datetime` (updated)
+
+[`datetime`](/standard/table-schema/#datetime)'s default `format` is now extended to allow optional milliseconds and timezone parts ([#23](https://github.com/frictionlessdata/datapackage/pull/23)).
+
+##### `geopoint` (updated)
+
+[`geopoint`](/standard/table-schema/#geopoint)'s definition now clarifies that floating point numbers can be used for coordinate definitions ([#14](https://github.com/frictionlessdata/datapackage/pull/14)).
+
+##### `any` (updated)
+
+[`any`](/standard/table-schema/#any) is now the default field type and clarifies that the field type should not be inferred if not provided ([#13](https://github.com/frictionlessdata/datapackage/pull/13)).
+
+#### Field Constraints
+
+##### `minimum` and `maximum` (updated)
+
+[`minimum`](/standard/table-schema/#minimum) and [`maximum`](/standard/table-schema/#maximum) are now extended to support the `duration` field type ([#8](https://github.com/frictionlessdata/datapackage/pull/8)).
+
+##### `exclusiveMinimum` and `exclusiveMaximum` (new)
+
+[`exclusiveMinimum`](/specifications/table-schema/#exclusiveminimum) and [`exclusiveMaximum`](/specifications/table-schema/#exclusivemaximum) can be used to specify exclusive minimum and maximum values ([#11](https://github.com/frictionlessdata/datapackage/pull/11)).
+
+##### `jsonschema` (new)
+
+[`jsonSchema`](/specifications/table-schema/#jsonschema) can be used for the `object` and `array` field types ([#32](https://github.com/frictionlessdata/datapackage/pull/32)).
+
+## v1.0
+
+> September 5, 2017
+
+Please refer to the [Data Package (v1) website](https://specs.frictionlessdata.io/).

content/docs/standard/introduction.md → content/docs/overview/introduction.md

@@ -1,7 +1,7 @@
 ---
 title: Introduction
 sidebar:
-  order: 1
+  order: 0
 ---
 
 In our increasingly data-driven world, the ability to manage, share, and analyze data effectively has become paramount. Organizations across various domains, from research institutions and governmental agencies to businesses and non-profit organizations, are generating and utilizing vast amounts of data to inform decisions, solve complex problems, and drive innovation. However, this data abundance brings with it a unique set of challenges, particularly when it comes to ensuring data quality, interoperability, and accessibility.

content/docs/recipes/data-catalog.md

@@ -122,8 +122,8 @@ Data packages can also be declared inline in the data catalog:
 }
 ```
 
-[dr]: /data-resource/
-[dp]: /data-package/
+[dr]: /standard/data-resource/
+[dp]: /standard/data-package/
 
 ## Implementations
 

content/docs/recipes/external-foreign-keys.md

@@ -15,12 +15,12 @@ This pattern allows users to link values in a field (or fields) in a Tabular Dat
 
 ## Specification
 
-The [`foreignKeys`](../../specifications/table-schema/#foreignkeys) array MAY have a property `package`. This property MUST be, either:
+The [`foreignKeys`](/standard/table-schema/#foreignkeys) array MAY have a property `package`. This property MUST be, either:
 
 - a string that is a fully qualified HTTP address to a Data Package `datapackage.json` file
-- a data package [`name`](../../specifications/data-package/#name) that can be resolved by a canonical data package registry
+- a data package [`name`](/standard/data-package/#name) that can be resolved by a canonical data package registry
 
-If the referenced data package has an [`id`](../../specifications/data-package/#id) that is a fully qualified HTTP address, it SHOULD be used as the `package` value.
+If the referenced data package has an [`id`](/standard/data-package/#id) that is a fully qualified HTTP address, it SHOULD be used as the `package` value.
 
 For example: