🔀 Merge pull request #24 from Fedodo/dev

Dev

CHANGELOG.md

@@ -6,17 +6,41 @@
 
 Useful links: Docsy [releases][] & [tags][]. Jump to the [latest][] release.
 
-For a list of issues targeted for the next release, see the [23Q1][] milestone.
+For a list of issues targeted for the next release, see the [23Q2][] milestone.
 
-## 0.7.0 - next planned release (unpublished yet)
+## [0.8.0][releases] - next major release (unpublished yet)
 
 **New**:
 
 **Breaking changes**:
 
+**Other changes**:
+
+## [0.7.1][]
+
+Followup changes to **Bootstrap (BS) 5.2 upgrade** ([#470]):
+
+- `td-blog-posts-list__item` and `td-blog-posts-list__body` replace the `.media`
+  and `.media-body` classes, dropped by BS 5 [#1560].
+- Docsy test for Bootstrap version has been made more robust, and can be
+  disabled. For details, see [#1579].
+
+[#1560]: https://github.com/google/docsy/issues/1560
+[#1579]: https://github.com/google/docsy/issues/1579
+
+## [0.7.0][]
+
+**New**:
+
+- **Click to copy button for Chroma-highlighted code blocks**: If you already
+  implemented this functionality on your website, you can disable it. For
+  details see [Chroma highlighting docs][chroma-docsy].
+
+**Breaking changes:**
+
+- [**Hugo** release][hugo-releases] **0.110.0** or later is required.
 - **Upgraded Bootstrap ([#470])** to v5.2. For a list of Bootstrap's breaking
-  changes, see the [Bootstrap migration guide][bsv5mig]. Other Docsy-specific
-  changes are listed below:
+  changes, see the [Bootstrap migration page][bsv5mig]. Docsy-specific changes:
   - Clean up of unused, or rarely used, variables, functions, and mixins:
     - Dropped `$primary-light`
     - Dropped `color-diff()`
@@ -29,29 +53,40 @@ For a list of issues targeted for the next release, see the [23Q1][] milestone.
   - Dropped support for pre-Hugo-0.54.x behavior of `{{% %}}`. ([#939])
   - `blocks/section`: **default** and accepted values of the `type` argument
     have changed! For details see [blocks/section] ([#1472]).
+  - **Card shortcodes** ([#1376])]:
+    - Renamed CSS class `td-card-deck` to `td-card-group`.
+    - `card`, `card-code`: markup of inner content (HTML/markdown) now depends
+      on the syntax of the calling shortcode, not on extension of page file any
+      more [#906].
+    - `card-code` is deprecated; use `card` with named parameter `code=true`
+      instead.
+
+[chroma-docsy]:
+  https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-chroma
 
-- **[Adaptation of shortcodes for diplay of cards (#1376)][1376]:
-  - shortcode `cardpane`: renamed CSS class `td-card-deck` to `td-card-group`.
-  - shortcode `card`, `card-code`: markup of inner content (html/markdown)
-    now depends on the syntax of the calling shortcode, not on extension
-    of page file any more [#906][906].
-  - shortcode `card-code` is now deprecated, use shortcode `card` with named
-    parameter `code=true` instead.
+- **Detection of draw.io diagrams** is now **disabled** by default [#1185][]
 
 **Other changes**:
 
+- `$list-inline-padding` is increased in support of footer icons ([#1523]). If
+  this global adjustment is a problem for your project, let us know and we can
+  contextualize the adjustment to the footer.
 - Non-breaking changes that result from the Bootstrap v5 upgrade:
   - Draw.io diagram edit button: replaced custom colors by BS's outline primary.
 
 [#470]: https://github.com/google/docsy/issues/470
 [#906]: https://github.com/google/docsy/issues/906
 [#939]: https://github.com/google/docsy/issues/939
+[#1185]: https://github.com/google/docsy/issues/1185
 [#1369]: https://github.com/google/docsy/issues/1369
+[#1376]: https://github.com/google/docsy/issues/1369
 [#1442]: https://github.com/google/docsy/issues/1442
 [#1472]: https://github.com/google/docsy/issues/1472
+[#1523]: https://github.com/google/docsy/pull/1523
 [blocks/section]:
   https://www.docsy.dev/docs/adding-content/shortcodes/#blockssection
 [bsv5mig]: https://getbootstrap.com/docs/5.2/migration/
+[hugo-releases]: https://github.com/gohugoio/hugo/releases
 
 ## [0.6.0][]
 
@@ -147,12 +182,16 @@ submodules. This has an impact on your project-build setup. To migrate your
 site, follow these steps (execute commands from your project's root directory):
 
 1.  Delete obsolete Docsy Git submodules:
-    ```console
-    $ rm -Rf themes/docsy/assets/vendor
+    ```sh
+    git rm themes/docsy/assets/vendor/Font-Awesome
+    git rm themes/docsy/assets/vendor/bootstrap
     ```
+    These commands remove the submodules from Git's tracking, from the
+    `.gitmodules` file, and deletes the submodule files under
+    `themes/docsy/assets/vendor`.
 2.  Get Docsy dependencies:
-    ```console
-    $ (cd themes/docsy && npm install)
+    ```sh
+    (cd themes/docsy && npm install)
     ```
 3.  Update your build scripts to fetch Docsy dependencies automatically. For
     example, if your site build uses NPM scripts, consider getting Docsy
@@ -223,14 +262,16 @@ For a full list of the changes to this release, see the [release notes][0.x.y].
 
 [@deining]: https://github.com/deining
 [@lisafc]: https://github.com/LisaFC
+[0.7.1]: https://github.com/google/docsy/releases/v0.7.1
+[0.7.0]: https://github.com/google/docsy/releases/v0.7.0
 [0.6.0]: https://github.com/google/docsy/releases/v0.6.0
 [0.5.1]: https://github.com/google/docsy/releases/v0.5.1
 [0.5.0]: https://github.com/google/docsy/releases/v0.5.0
 [0.4.0]: https://github.com/google/docsy/releases/v0.4.0
 [0.3.0]: https://github.com/google/docsy/releases/v0.3.0
 [0.2.0]: https://github.com/google/docsy/releases/v0.2.0
 [0.x.y]: #
-[23q1]: https://github.com/google/docsy/milestone/6
+[23q2]: https://github.com/google/docsy/milestone/7
 [hugo modules]: https://gohugo.io/hugo-modules/
 [latest]: https://github.com/google/docsy/releases/latest
 [releases]: https://github.com/google/docsy/releases

CONTRIBUTING.md

@@ -29,6 +29,10 @@ information on using pull requests.
 This project follows
 [Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
 
+## Student contributions
+
+Docsy welcomes contributions from students. However, we cannot guarantee that PRs will be merged within any specific timeframe. We ask that instructors *not* create assignments requiring students to have PRs merged into the project. We will not merge PRs solely to satisfy any class assignments.
+
 ## How to contribute
 
 See the [contribution guidelines][] in the Docsy user guide.

README.md

@@ -1,5 +1,12 @@
 # Docsy
-## 🚧 WARNING: `main` is unstable! For details, see [#1359](https://github.com/google/docsy/discussions/1359) 🚧
+
+[![Project status: active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![Project releases](https://img.shields.io/github/release/google/docsy)](https://github.com/google/docsy/releases)
+[![Project build Status](https://badges.netlify.com/api/docsydocs.svg?branch=master)](https://app.netlify.com/sites/docsydocs/deploys)
+[![Project contributors](https://img.shields.io/github/contributors/google/docsy)](https://github.com/google/docsy/graphs/contributors)
+[![Project license](https://img.shields.io/github/license/google/docsy)](https://github.com/google/docsy/blob/main/LICENSE)
+
+## 🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use official Docsy [releases].
 
 Docsy is a [Hugo](https://gohugo.io) theme for technical documentation sets,
 providing simple navigation, site structure, and more.
@@ -13,52 +20,54 @@ The following are basic prerequisites for using Docsy in your site:
 
 - Install a recent release of the Hugo "extended" version. If you install from
   the [Hugo release page](https://github.com/gohugoio/hugo/releases), make sure
-  you download the `_extended` version which supports SCSS.
+  you download the `extended` version, which supports SCSS.
 
 - Install `PostCSS` so that the site build can create the final CSS assets. You
   can install it locally by running the following commands from the root
   directory of your project:
 
-  ```console
-  $ npm install --save-dev autoprefixer
-  $ npm install --save-dev postcss-cli
+  ```sh
+  npm install --save-dev autoprefixer
+  npm install --save-dev postcss-cli
   ```
-  
-  Starting in [version 8 of `postcss-cli`](https://github.com/postcss/postcss-cli/blob/master/CHANGELOG.md),
+
+  Starting in
+  [version 8 of `postcss-cli`](https://github.com/postcss/postcss-cli/blob/master/CHANGELOG.md),
   you must also separately install `postcss`:
 
-  ```bash
+  ```sh
   npm install -D postcss
   ```
-  
-Any additional prerequisites depend on the [installation option](https://www.docsy.dev/docs/get-started/#installation-options)
-you choose. We recommend using Docsy as a Hugo module, which requires that
-you have the `go` language installed in addition to Hugo and PostCSS.
 
-For complete prerequisites and instructions, see our [Get started guides](https://www.docsy.dev/docs/get-started/).
+Any additional prerequisites depend on the
+[installation option](https://www.docsy.dev/docs/get-started/#installation-options)
+you choose. We recommend using Docsy as a Hugo module, which requires that you
+have the `go` language installed in addition to Hugo and PostCSS.
+
+For complete prerequisites and instructions, see our
+[Get started guides](https://www.docsy.dev/docs/get-started/).
 
 ## Example and usage
 
-You can find an example project that uses Docsy in the [Docsy Example Project
-repo](https://github.com/google/docsy-example).The Docsy Example Project is
-hosted at [example.docsy.dev](https://example.docsy.dev). For
+You can find an example project that uses Docsy in the
+[Docsy Example Project repo](https://github.com/google/docsy-example).The Docsy
+Example Project is hosted at [example.docsy.dev](https://example.docsy.dev). For
 real-life examples of sites that use Docsy (and their source repos), see our
 [Examples](https://www.docsy.dev/docs/examples/) page.
 
 To use the Docsy theme for your own site:
 
-- (Recommended) Use the [example
-  project](https://github.com/google/docsy-example), which includes the Docsy
-  theme as a Hugo module, as a template to create your project. You can customize
-  this pre-configured basic site into your own Docsy themed site. [Learn
-  more...](https://github.com/google/docsy-example)
+- (Recommended) Use the
+  [example project](https://github.com/google/docsy-example), which includes the
+  Docsy theme as a Hugo module, as a template to create your project. You can
+  customize this pre-configured basic site into your own Docsy themed site.
+  [Learn more...](https://github.com/google/docsy-example)
 
-- Add Docsy to your existing Hugo site. You can
-  add Docsy as a Hugo module, as a Git submodule, or clone the Docsy theme into your
-  project.
+- Add Docsy to your existing Hugo site. You can add Docsy as a Hugo module, as a
+  Git submodule, or clone the Docsy theme into your project.
 
-See the [Get started guides](https://www.docsy.dev/docs/get-started/)
-for details about the various usage options.
+See the [Get started guides](https://www.docsy.dev/docs/get-started/) for
+details about the various usage options.
 
 ## Documentation
 
@@ -71,27 +80,27 @@ Alternatively you can use Hugo to generate and serve a local copy of the guide
 (also useful for testing local theme changes), making sure you have installed
 all the prerequisites listed above:
 
-```console
-$ git clone --depth 1 https://github.com/google/docsy.git
-$ cd docsy/userguide/
-$ npm install
-$ npm run serve
+```sh
+git clone --depth 1 https://github.com/google/docsy.git
+cd docsy/userguide/
+npm install
+npm run serve
 ```
 
-## Contributing ![GitHub](https://img.shields.io/github/contributors/google/docsy)
+## Contributing
 
 Please read
-[CONTRIBUTING.md](https://github.com/google/docsy/blob/main/CONTRIBUTING.md)
-for details on our code of conduct, and the process for submitting pull requests
-to us. See also the list of
+[CONTRIBUTING.md](https://github.com/google/docsy/blob/main/CONTRIBUTING.md) for
+details on our code of conduct, and the process for submitting pull requests to
+us. See also the list of
 [contributors](https://github.com/google/docsy/graphs/contributors) who
 participated in this project.
 
-## License ![GitHub](https://img.shields.io/github/license/google/docsy)
+## License
 
 This project is licensed under the Apache License 2.0 - see the
-[LICENSE.md](https://github.com/google/docsy/blob/main/LICENSE) file for
-details
+[LICENSE.md](https://github.com/google/docsy/blob/main/LICENSE) file for details
 
-[Deploys]: https://app.netlify.com/sites/docsydocs/deploys
-[Netlify]: https://netlify.com
+[deploys]: https://app.netlify.com/sites/docsydocs/deploys
+[netlify]: https://netlify.com
+[releases]: https://github.com/google/docsy/releases