diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 0000000..a54eb33 --- /dev/null +++ b/docs/.pages @@ -0,0 +1,13 @@ +nav: +- Home: home.md +- getting-started.md +# - Style Guidelines: ./style-guidelines +# - How-tos: ./style-guidelines + # - disambiguation: ./style-guidelines/disambiguation.md + # - author: ./style-guidelines/entities/author.md +- ... # List all pages and their subdirectories +- Glossary: glossary.md +- contribute.md +- Reference: + - Style process: ./.reference/style-process.md + - Browser support: ./.reference/browser-suppoer.md \ No newline at end of file diff --git a/docs/reference/browser-support.md b/docs/.reference/browser-support.md similarity index 100% rename from docs/reference/browser-support.md rename to docs/.reference/browser-support.md diff --git a/docs/reference/style-process.md b/docs/.reference/style-process.md similarity index 100% rename from docs/reference/style-process.md rename to docs/.reference/style-process.md diff --git a/docs/getting-started.md b/docs/getting-started.md index 2af415a..0497385 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -33,7 +33,7 @@ The publisher [Orbit Books](https://bookbrainz.org/publisher/b065b24d-136f-45e3- ## How do I add a book? -Now that you know a bit more about BookBrainz and you're excited to contribute, have a look at our tutorial on [how to add a book](./tutorials/add-a-book.md). +Now that you know a bit more about BookBrainz and you're excited to contribute, have a look at our tutorial on [how to add a book](./how-to/add-a-book.md). ## Can I create a digital bookshelf? diff --git a/docs/home.md b/docs/home.md index a073c0a..0efd68e 100644 --- a/docs/home.md +++ b/docs/home.md @@ -10,14 +10,14 @@ The process for this will take you to the MusicBrainz website where you can crea Then head over to the [Getting started](./getting-started.md) page of this user guide to learn the basics of editing in BookBrainz. +## In this user guide +{nav} + ## Accessing the data The BookBrainz data is freely available to everyone, for any use. Please see our [licensing page](https://bookbrainz.org/licensing) for more details. - Regular database dumps of our (Postgres) database can be found [at this address](http://ftp.musicbrainz.org/pub/musicbrainz/bookbrainz/). - We also have an API (or webservice) under development [with live documentation](https://api.test.bookbrainz.org/1/docs/) to access the data programmatically. - ## Contact and updates Any questions? You can get in contact with the community on [our IRC channel](https://kiwiirc.com/nextclient/irc.libera.chat/?#bookbrainz) or [our forums](https://community.metabrainz.org/c/bookbrainz), or send us [an email](mailto:bookbrainz@metabrainz.org) ! diff --git a/docs/tutorials/add-a-book.md b/docs/how-to/add-a-book.md similarity index 100% rename from docs/tutorials/add-a-book.md rename to docs/how-to/add-a-book.md diff --git a/docs/tutorials/merge.md b/docs/how-to/merge.md similarity index 100% rename from docs/tutorials/merge.md rename to docs/how-to/merge.md diff --git a/docs/tutorials/series.md b/docs/how-to/series.md similarity index 100% rename from docs/tutorials/series.md rename to docs/how-to/series.md diff --git a/docs/style/.pages.yml b/docs/style/.pages.yml new file mode 100644 index 0000000..fb01774 --- /dev/null +++ b/docs/style/.pages.yml @@ -0,0 +1,2 @@ +nav: +- ... # List all pages and their subdirectories \ No newline at end of file diff --git a/docs/style/entities/author.md b/docs/style/entities/author.md index 2bcb131..7f9cbdb 100644 --- a/docs/style/entities/author.md +++ b/docs/style/entities/author.md @@ -74,8 +74,8 @@ It contains stories by 21 authors, but on the cover of the book the most promine - This is where Author Credits come in: here the Edition of [*Rogues* ](https://bookbrainz.org/edition/6c051f2b-3d49-4e07-9282-eeb85dd35655) is *credited to* [George R. R. Martin](https://bookbrainz.org/author/8b0b4bfa-16c4-48f1-bd45-b416a3ca420b) & [Gardner Dozois](https://bookbrainz.org/author/b87edc09-87ec-4d92-b589-fec1cea47a63) following the cover. - The 6 other authors named on the cover as well as the other 15 authors represented in the book do not appear in the Author Credits. 2. The children's book [*Charlie the Choo-Choo*](https://bookbrainz.org/edition/dd16f9d9-3ee1-436e-a0b2-a216377e93ef) was published by [Stephen King](https://bookbrainz.org/author/128d9490-ee19-4270-a070-32e0a36847f5) under the [pen name](#pen-names) "Beryl Evans". - - The Edition is *credited to* [Beryl Evans](https://bookbrainz.org/author/128d9490-ee19-4270-a070-32e0a36847f5) (links to the Stephen king entry) - - The Work entity [*Charlie the Choo-Choo*](https://bookbrainz.org/work/b0b5f6d7-39e7-4515-924b-974277593f54) contained in the Edition has the relationship "was written by [Stephen King]((https://bookbrainz.org/author/128d9490-ee19-4270-a070-32e0a36847f5))" + - The Edition is *credited to* [Beryl Evans](https://bookbrainz.org/author/128d9490-ee19-4270-a070-32e0a36847f5) (links to the Stephen King entry) + - The Work entity [*Charlie the Choo-Choo*](https://bookbrainz.org/work/b0b5f6d7-39e7-4515-924b-974277593f54) contained in the Edition has the relationship "was written by [Stephen King](https://bookbrainz.org/author/128d9490-ee19-4270-a070-32e0a36847f5)" ## Current Author-linking relationships are: diff --git a/docs/style/entities/work.md b/docs/style/entities/work.md index d23b52d..6e02f8e 100644 --- a/docs/style/entities/work.md +++ b/docs/style/entities/work.md @@ -45,7 +45,7 @@ Additionally, a work can be translated into the same language several times, eac A translated work should have:
- a relationship added to the original work it is a translation of -- a relationship to the author that wrote the original (see [provided story](./author#current-author-linking-relationships-are) relationship) +- a relationship to the author that wrote the original (see [provided story](author.md#current-author-linking-relationships-are) relationship) - and a translator relationship to its translator. Examples: @@ -70,7 +70,7 @@ example: --> ## What should works be named? Generally this should be straightforward, e.g. the work for the book [The Silmarillion](https://bookbrainz.org/edition/6d2273eb-2f4e-444f-be61-15f0c23e7451) by Tolkien is called "[The Silmarillion](https://bookbrainz.org/work/e6b73035-4bf5-4989-a877-291d98309e8b)"
-Adaptations can often have descriptive subtitles, but if not this information should be put in the disambiguation, for translations, the name should be what is on that translation's cover. Any additional names, such as descriptive titles, known variations or transliterations, should be added as [Aliases](/glossary). +Adaptations can often have descriptive subtitles, but if not this information should be put in the disambiguation, for translations, the name should be what is on that translation's cover. Any additional names, such as descriptive titles, known variations or transliterations, should be added as [Aliases](../../glossary.md). The language the work's _name_ is in, can differ from the language the work as a whole is written in. For example, a work written in English can have a Latin name. The name of the work should _generally_ be capitalized based on the rules for the language of its name.
@@ -124,7 +124,7 @@ Linking works together: * works * adaptation -links a work that is an [adaptation](### When to create new works?) of another work. +links a work that is an [adaptation](#when-to-create-new-works) of another work. * translation links a work that is a translation of another work, remember to add a link to the works translator here, but the original author should have *provided story* * revision diff --git a/docs/style/index.md b/docs/style/index.md new file mode 100644 index 0000000..827cc18 --- /dev/null +++ b/docs/style/index.md @@ -0,0 +1,5 @@ +# Style Guidelines + +This page outlines the official BookBrainz Style Guidelines. + +{nav} diff --git a/docs/style/overview.md b/docs/style/overview.md deleted file mode 100644 index 4d79769..0000000 --- a/docs/style/overview.md +++ /dev/null @@ -1,2 +0,0 @@ -# Style Guidelines -[TOC] diff --git a/mkdocs.yml b/mkdocs.yml index 021d176..0fa40bb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,3 +19,6 @@ markdown_extensions: - nl2br extra_css: - style.css +plugins: + - awesome-pages # Required for pagenav-generator + - pagenav-generator diff --git a/requirements.txt b/requirements.txt index 3cdaf53..40d7451 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,4 +3,6 @@ commonmark==0.9.1 recommonmark==0.5.0 jinja2==3.1.6 mkdocs==1.6.1 -mkdocs-custommill==1.3.0 \ No newline at end of file +mkdocs-custommill==1.3.0 +mkdocs-awesome-pages-plugin==2.10.1 +mkdocs-pagenav-generator @ git+https://github.com/Andre601/mkdocs-pagenav-generator@acb5b15