website: Add Kramdown extension for outdated page notices
This commit implements an outdated notice element which can easily flag
outdated documentation.
'{: .outdated-notice}' will generate an outdated notice element wherever
it occurs in a .md file, beginning with
"Note: This page is outdated."
in bold font. Any text immediately succeeding it will be included in the
notice as a comment.
Change-Id: I987e019ad322fc61a4c5bf4d4d3dd295d3503167
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5-website/+/26563
Reviewed-by: Jason Lowe-Power <jason@lowepower.com>
Maintainer: Jason Lowe-Power <jason@lowepower.com>
Tested-by: Jason Lowe-Power <jason@lowepower.com>
diff --git a/README.md b/README.md
index b4f784a..135eff2 100755
--- a/README.md
+++ b/README.md
@@ -241,6 +241,21 @@
Place the file in _pages/documentation. Make sure to add the page to the documentation navigation, explained by the section above.
+#### Indicating outdated information
+
+To flag information in a page as valid, use an outdated notice in the .md file of that page:
+
+```
+{: .outdated-notice}
+This page is outdated!
+```
+
+This will be replaced by a warning element containing the text "**Note: This page is outdated.**", followed by the content succeeding the notice - in this case, "This page is outdated!". In this way, you can add additional information explaining why or how the page is outdated, and general tips on what to do to mitigate this issue.
+
+Notes:
+
+Make sure that the text following `{: .outdated-notice}` is not used as a title, heading, or any other important Markdown element, as it will be incorporated into the outdated notice and break formatting.
+
## Blog
Add blog page to _posts folder.
diff --git a/_sass/_notice.scss b/_sass/_notice.scss
new file mode 100644
index 0000000..150501e
--- /dev/null
+++ b/_sass/_notice.scss
@@ -0,0 +1,90 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2013-2020 Michael Rose and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * Code adopted from the Minimal Mistakes codebase at:
+ * https://github.com/mmistakes/minimal-mistakes/blob/master/_sass/minimal-mistakes/_notices.scss
+ */
+
+@mixin notice($notice-color) {
+ margin: 2em 0 !important; /* override*/
+ padding: 1em;
+ color: $font-color;
+ font-family: $font-style;
+ font-size: 1.12em;
+ text-indent: initial; /* override*/
+ background-color: mix(#fff, $notice-color, 90%);
+ border-radius: 0;
+ box-shadow: 0 1px 1px rgba($notice-color, 0.25);
+
+ h4 {
+ margin-top: 0 !important; /* override*/
+ margin-bottom: 0.75em;
+ }
+
+ @at-root .page__content #{&} h4 {
+ /* using at-root to override .page-content h4 font size*/
+ margin-bottom: 0;
+ font-size: 1em;
+ }
+
+ p {
+ &:last-child {
+ margin-bottom: 0 !important; /* override*/
+ }
+ }
+
+ h4 + p {
+ /* remove space above paragraphs that appear directly after notice headline*/
+ margin-top: 0;
+ padding-top: 0;
+ }
+
+ a {
+ color: $notice-color;
+
+ &:hover {
+ color: mix(#000, $notice-color, 40%);
+ }
+ }
+
+ code {
+ background-color: mix(#fff, $notice-color, 95%)
+ }
+
+ ul {
+ &:last-child {
+ margin-bottom: 0; /* override*/
+ }
+ }
+}
+
+/* Outdated notice */
+.outdated-notice {
+ @include notice($main);
+}
+
+/* Insert a base outdated warning message to any inclusion of .outdated-notice. */
+.outdated-notice:before {
+ content: 'Note: This page is outdated. ';
+ font-weight: bold;
+}
diff --git a/css/main.scss b/css/main.scss
index 1339dc5..fe0249d 100755
--- a/css/main.scss
+++ b/css/main.scss
@@ -1,7 +1,8 @@
---
# Front matter comment to ensure Jekyll properly reads file.
---
-@import
- "base",
+@import
+ "base",
"layout",
- "syntax-highlighting"
\ No newline at end of file
+ "syntax-highlighting",
+ "notice"
