Add Gradle Cookbook landing and Cross-references

docs/CONTRIBUTING.md

@@ -1,31 +1,58 @@
-# Contributing to the Community Site
+# Contributing to the Gradle Community Site
+
+[![a](https://img.shields.io/badge/slack-%23docs-brightgreen?style=flat&logo=slack)](./contributing/community-slack.md)
 
 Contributing to this site is easy!
+While we may not have many issues for newcomers,
+we welcome all contributions, big or small. 
+
+Many minor changes can be made directly from your browser.
 Just submit a pull request to the respective repository.
 On the rop right corner you can also see the _Edit_ icons
 that will normally get you right to the content page.
 
-We do not have so many newcomer friendly issues in this repository,
-but you are welcome to submit any small and big patches!
+For bigger changes, you can develop locally. 
+Detailed instructions are provided below.
+
+## Communication channels
+
+- `#docs` on the [Gradle Community Slack](./contributing/community-slack.md)
+
+## Contributing Content
+
+### Contributing to Gradle Cookbok
+
+See the [Gradle Cookbook Contributor Guide](./cookbook/CONTRIBUTING.md).
 
-## Technology under the hood
+### Other locations
+
+The Gradle website is in the early stages of development,
+and we do not have fixed processes and practices yet.
+Just submit a pull request with your change.
+If you have any concerns, let's discuss them on Slack or in a GitHub issue.
+
+## Developing the site
+
+It is possible to deploy the site instance locally or inside a Dev Container.
+The latter is the recommended approach.
+
+### Technology under the hood
 
 The community site is built with [MkDocs](https://www.mkdocs.org/),
 [MkDocs Multirepo Plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin/tree/main),
 and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material).
 So, it uses the Python technology stack instead of Gradle,
 but on the other hand we're leveraging one of the most powerful documentation engines.
 
-## Preparing the environment
-
-It is possible to deploy the site instance locally or inside a Dev Container.
+### Setting up the environment
 
-### Dev Container
+#### Dev Containers
 
 This repository includes the Dev Container definition that you can use in Visual Studio Code or in IntelliJ Platform
 to spin up the local development environment.
+The same Dev Container is used for CI/CD, and it is the recommended way for local development.
 
-### Running locally
+#### Running locally
 
 Requirements:
 
@@ -40,7 +67,7 @@ pip install -r .devcontainer/requirements.txt
 mkdocs build
 ```
 
-## Local development
+### Local development
 
 Once you have the ready to build environment,
 you can use `mkdocs build` to build the static site.

docs/contributing/documentation/README.md

@@ -7,23 +7,33 @@ All contributions are welcome!
 
 - Join the community Slack workspace
 - Use the `#docs` channel to discuss any documentation matters
-- If your pull request gets stuck, do not hesitate to ask in `#docs` or in `#contributing` channels
+- If your pull request gets stuck, do not hesitate to ask in the `#docs` or `#contributing` channels
 
 ## Locations
 
-- [Contributing to the Gradle Build Tool documentation](../../gradle/CONTRIBUTING/#contributing-to-documentation) -
-  - This repository includes Gradle documentation sources, including but not limited to: User Manual, DSL Reference, documentation for core plugins and Javadoc
-  - Implementation: Asciidoc + custom documentation engine
+- [Gradle Build Tool - User Manual on docs.gradle.org/](https://docs.gradle.org/)
+    - This site includes main Gradle documentation sources, including but not limited to: User Manual, DSL Reference, documentation for core plugins and Javadoc
+    - Implementation: Asciidoc + custom documentation engine
+    - [Contributor Guide](../../gradle/CONTRIBUTING/#contributing-to-documentation)
+- [Gradle Cookbook](../../cookbook/README.md) - a collection of recipes, guides and examples for the Gradle Build Tool.
+    - This is an additional solution-based documentation
+    - Implementation: MkDocs + Material for MkDocs
+    - [Contributor Guide](../../cookbook/CONTRIBUTING.md)
 - Plugin documentation - Documentation for the key plugins is provided by the Gradle Build Tool repo.
   For other plugins, see their repositories for the docs and contributing guidelines.
-  - Implementation: most plugins use simple documentation pages in GitHub-flavored Markdown (`README.md`).
-- [Contributing to the Community site](../../CONTRIBUTING.md) -
-  Community resources on this website
-  - Implementation - Markdown + MkDocs
+    - Implementation: most plugins use simple documentation pages in GitHub-flavored Markdown (`README.md`).
+- [Gradle Community Site](https://community.gradle.org/) -
+  Community resources, including [Gradle Cookbook](../../cookbook/README.md) and top-level [Gradle Contributor Guide](../README.md)
+    - Implementation - Markdown + MkDocs
+    - [Contributor Guide](../../CONTRIBUTING.md)
 
 ## Tools
 
 In Gradle we use a diverse set of tooling for documentation development.
+We use both Markdown and Asciidoc for writing,
+with MkDocs, Jekyll, and the Gradle Asciidoc Plugin as our main tools for documentation.
+Additionally, we utilize other tools such as Dokka, Javadoc, and OpenAPI specifications.
+
 Many small patches can be just submitted from the GitHub web editor.
 For bigger patches and local development, see the referenced contributing guidelines.
 

docs/cookbook/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to the Gradle Cookbook
+
+[![a](https://img.shields.io/badge/slack-%23docs-brightgreen?style=flat&logo=slack)](./contributing/community-slack.md)
+
+
+The Gradle Cookbook is under active development.
+Any contributions are welcome!
+
+## Discuss
+
+- `#docs` on the [Gradle Community Slack](../contributing/community-slack.md)
+- [GitHub Issues](https://github.com/gradle/community/issues)
+
+## HOWTOs
+
+### Editing and Adding Pages
+
+A few tips:
+
+- All the pages on this site are written in Markdown.
+- If needed, we have various tools available, such as code templates and macros, and we can add more MkDocs plugins if necessary.
+- The Table of Contents is currently located in [mkdocs.yml](../mkdocs.yml).
+When adding new pages, please update the ToC to ensure they are discoverable.
+
+### Adding New Categories
+
+At the moment, we add categories based on consensus.
+If you plan to add a new major category, it's better to discuss it in advance.
+
+## References
+
+- [Main community.gradle.org contributor guide](../CONTRIBUTING.md) - describes how to contribute and how to set up the local environment if needed

docs/cookbook/README.md

@@ -1,6 +1,60 @@
-# The Gradle Cookbook
+---
+title: "The Gradle Cookbook"
+description: >
+  Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool.
+---
 
-This is a collection of guides and examples for the Gradle Build Tool.
+Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool.
+The goal of this portal is to offer solution-based documentation for end users,
+including but not limited to key use cases like
+publishing to Maven Central,
+CI/CD tool and IDE integrations,
+support for languages and frameworks,
+troubleshooting Gradle Build Tool,
+etc.
 
-## Table of contents
-* [Gradle Built Tool on CI](/community/cookbook/ci/jenkins/)
+In this document, _Gradle Build Tool_ is abbreviated _Gradle_.
+
+!!! note
+    The Gradle Cookbook is under active development.
+    Its structure and links may change, and we're working on adding more content.
+    Any contributions are welcome, see the [Contributor Guide](./CONTRIBUTING.md)!
+
+## Why and How?
+
+The Gradle Build Tool ecosystem is huge, it includes many plugins, integrations, developer tools and other components.
+Not all of them can be covered in the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html)
+which represents core documentation maintained for each Gradle release.
+Moreover, being tied to the Gradle release contribution process and the release cycle makes it more difficult to contribute there.
+Maintaining documentation has been challenging for us as well,
+leading to many outdated pages.
+
+So, we decided to build a second resource as an extension to the Gradle User Manual,
+with the following in mind:
+
+- Gradle Cookbook remains an official resource under `community.gradle.org`.
+  It is not a second-class citizen, just another structure that is not tied to the Gradle release cycle
+- Pages should be focused on offering solutions to end users for particular use cases,
+  hence the _Cookbook_
+- We follow the Wiki-alike collaboration style,
+  with a lower barrier to contribute than `gradle/gradle`.
+  Some sections can get explicit maintainers/reviewers over time.
+- We use Documentation-as-Code, with simple Markdown or Asciidoc files used as a source
+- Minimizing duplication.
+  We can include documentation from other sources under the [Gradle GitHub organization](https://github.com/gradle/)
+
+## Table of Contents
+
+- [Gradle Built Tool on CI](/community/cookbook/ci/jenkins/)
+
+## Contributing
+
+Contributions are welcome!
+You can extend the Cookbook by adding new recipes, updating the existing ones,
+or even creating whole new sections.
+Check out the [Contributor Guide](./CONTRIBUTING.md) for more information.
+
+## References
+
+- [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html)
+- [Other Documentation Locations](../contributing/documentation/README.md/#locations)

mkdocs.yml

@@ -53,13 +53,12 @@ theme:
     - search.suggest
     - toc.follow
     - toc.integrate
-  palette: 
-
+  palette:
     - scheme: default
       media: "(prefers-color-scheme: light)"
       primary: custom
       toggle:
-        icon: material/brightness-7 
+        icon: material/brightness-7
         name: Switch to dark mode
 
     - scheme: slate
@@ -98,19 +97,20 @@ extra:
     - icon: fontawesome/brands/mastodon
       link: https://mastodon.social/@Gradle
       name: Mastodon
+  analytics:
+    provider: google
+    property: G-7W7NC6YNPT
 
-analytics:
-  provider: google
-  property: G-7W7NC6YNPT
-
 nav:
   - Home: README.md
   - Cookbook:
+    - Overview: cookbook/README.md
     - Gradle on CI:
       - Jenkins: cookbook/ci/jenkins.md
       - TeamCity: cookbook/ci/teamcity.md
       - GitHub Actions: cookbook/ci/github-actions.md
       - Travis CI: cookbook/ci/travis-ci.md
+    - Contributing: cookbook/CONTRIBUTING.md
   - Participate:
     - Getting Started: contributing/README.md
     - Community Slack: contributing/community-slack.md
@@ -144,7 +144,7 @@ nav:
 #    - Develocity: https://gradle.com/develocity
 #    - Service Providers: https://gradle.org/services/
 #    - Training: https://gradle.org/courses
-    
+
 plugins:
   - search
   - autorefs
@@ -155,7 +155,7 @@ plugins:
   - social
   - group:
       enabled: !ENV [FULL_BUILD, true]
-      plugins:  
+      plugins:
       - multirepo:
           cleanup: false
           keep_docs_dir: true
@@ -179,19 +179,21 @@ plugins:
             imports: [ "README.md", "*" ]
 
   - redirects:
-     redirect_maps:
-        
+      redirect_maps:
+
 # Markdown
 markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
+  - pymdownx.details
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
   - toc:
       permalink: '#'
+  - admonition
   - attr_list