From 239cc780d9ed3d0d807c14c08c651d9c91ea5b44 Mon Sep 17 00:00:00 2001 From: Sarah-okolo Date: Mon, 9 Sep 2024 12:07:33 +0100 Subject: [PATCH 1/6] Redesigned site look, layout and mobile view --- content/about-block-inline-tags.md | 1 + content/about-commandline.md | 3 +- content/about-configuring-default-template.md | 1 + content/about-configuring-jsdoc.md | 1 + content/about-getting-started.md | 85 ----- content/about-including-package.md | 1 + content/about-including-readme.md | 1 + content/about-license-jsdoc3.md | 1 + content/about-namepaths.md | 3 +- content/about-plugins.md | 1 + content/about-tutorials.md | 1 + content/data/redirects.yaml | 13 + content/howto-amd-modules.md | 1 + content/howto-commonjs-modules.md | 1 + content/howto-es2015-classes.md | 1 + content/howto-es2015-modules.md | 1 + content/includes/index.njk | 56 +++- content/includes/layout.njk | 34 +- content/index.md | 84 ++++- content/plugins-markdown.md | 1 + content/tags-abstract.md | 4 +- content/tags-access.md | 2 + content/tags-alias.md | 2 + content/tags-async.md | 2 + content/tags-augments.md | 2 + content/tags-author.md | 2 + content/tags-borrows.md | 2 + content/tags-callback.md | 2 + content/tags-class.md | 2 + content/tags-classdesc.md | 2 + content/tags-constant.md | 2 + content/tags-constructs.md | 2 + content/tags-copyright.md | 2 + content/tags-default.md | 2 + content/tags-deprecated.md | 2 + content/tags-description.md | 2 + content/tags-enum.md | 2 + content/tags-event.md | 2 + content/tags-example.md | 2 + content/tags-exports.md | 2 + content/tags-external.md | 2 + content/tags-file.md | 2 + content/tags-fires.md | 2 + content/tags-function.md | 2 + content/tags-generator.md | 2 + content/tags-global.md | 6 +- content/tags-hideconstructor.md | 2 + content/tags-ignore.md | 2 + content/tags-implements.md | 2 + content/tags-inheritdoc.md | 2 + content/tags-inline-link.md | 10 +- content/tags-inline-tutorial.md | 10 +- content/tags-inner.md | 10 +- content/tags-instance.md | 8 +- content/tags-interface.md | 2 + content/tags-kind.md | 10 +- content/tags-lends.md | 2 + content/tags-license.md | 2 + content/tags-listens.md | 2 + content/tags-member.md | 2 + content/tags-memberof.md | 2 + content/tags-mixes.md | 2 + content/tags-mixin.md | 2 + content/tags-module.md | 2 + content/tags-name.md | 6 +- content/tags-namespace.md | 8 +- content/tags-override.md | 2 + content/tags-package.md | 2 + content/tags-param.md | 2 + content/tags-private.md | 2 + content/tags-property.md | 2 + content/tags-protected.md | 2 + content/tags-public.md | 2 + content/tags-readonly.md | 6 +- content/tags-requires.md | 6 +- content/tags-returns.md | 2 + content/tags-see.md | 4 +- content/tags-since.md | 4 +- content/tags-static.md | 10 +- content/tags-summary.md | 4 +- content/tags-this.md | 6 +- content/tags-throws.md | 6 +- content/tags-todo.md | 6 +- content/tags-tutorial.md | 4 +- content/tags-type.md | 4 +- content/tags-typedef.md | 4 +- content/tags-variation.md | 2 + content/tags-version.md | 2 + content/tags-yields.md | 2 + eleventy.config.js | 1 + lib/nav-sidebar.js | 78 +++++ styles/_variables.css | 63 ++++ styles/css3-github-ribbon.css | 26 +- styles/hljs-tomorrow.css | 47 +-- styles/usejsdoc.css | 317 +++++++++++++++--- 95 files changed, 806 insertions(+), 249 deletions(-) delete mode 100644 content/about-getting-started.md create mode 100644 lib/nav-sidebar.js create mode 100644 styles/_variables.css diff --git a/content/about-block-inline-tags.md b/content/about-block-inline-tags.md index e0a81812..306f39fd 100644 --- a/content/about-block-inline-tags.md +++ b/content/about-block-inline-tags.md @@ -1,6 +1,7 @@ --- title: Block and inline tags tags: gettingStarted +layout: index.njk --- ## Overview diff --git a/content/about-commandline.md b/content/about-commandline.md index 40c4c9a7..4e1cc01e 100644 --- a/content/about-commandline.md +++ b/content/about-commandline.md @@ -1,13 +1,14 @@ --- title: Command-line arguments to JSDoc tags: gettingStarted +layout: index.njk related: - /about-configuring-jsdoc --- At its most basic level, JSDoc is used like so: - /path/to/jsdoc yourSourceCodeFile.js anotherSourceCodeFile.js ... + `/path/to/jsdoc yourSourceCodeFile.js anotherSourceCodeFile.js ...` where `...` are paths to other files to generate documentation for. diff --git a/content/about-configuring-default-template.md b/content/about-configuring-default-template.md index 107825f6..31e7c6bc 100644 --- a/content/about-configuring-default-template.md +++ b/content/about-configuring-default-template.md @@ -1,6 +1,7 @@ --- title: Configuring JSDoc's default template tags: gettingStarted +layout: index.njk related: - /about-configuring-jsdoc --- diff --git a/content/about-configuring-jsdoc.md b/content/about-configuring-jsdoc.md index 759e5e0e..3c1b4c56 100644 --- a/content/about-configuring-jsdoc.md +++ b/content/about-configuring-jsdoc.md @@ -1,6 +1,7 @@ --- title: Configuring JSDoc with a configuration file tags: gettingStarted +layout: index.njk related: - /about-commandline - /about-plugins diff --git a/content/about-getting-started.md b/content/about-getting-started.md deleted file mode 100644 index 121efd83..00000000 --- a/content/about-getting-started.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Getting Started with JSDoc 3 -tags: gettingStarted ---- - -## Getting started - -JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You -add documentation comments directly to your source code, right alongside the code itself. The JSDoc -tool will scan your source code and generate an HTML documentation website for you. - -## Adding documentation comments to your code - -JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that -you will want to document things like modules, namespaces, classes, methods, method parameters, and -so on. - -JSDoc comments should generally be placed immediately before the code being documented. Each comment -must start with a `/**` sequence in order to be recognized by the JSDoc parser. Comments beginning -with `/*`, `/***`, or more than 3 stars will be ignored. This is a feature to allow you to suppress -parsing of comment blocks. - -::: example "The simplest documentation is just a description" - -```js -/** This is a description of the foo function. */ -function foo() { -} -``` -::: - -Adding a description is simple—just type the description you want in the documentation comment. - -Special "JSDoc tags" can be used to give more information. For example, if the function is a -constructor for a class, you can indicate this by adding a `@constructor` tag. - -::: example "Use a JSDoc tag to describe your code" - -```js -/** - * Represents a book. - * @constructor - */ -function Book(title, author) { -} -``` -::: - -More tags can be used to add more information. See the [home page][block-tags] for a complete list -of tags that are recognized by JSDoc 3. - -::: example "Adding more information with tags" - -```js -/** - * Represents a book. - * @constructor - * @param {string} title - The title of the book. - * @param {string} author - The author of the book. - */ -function Book(title, author) { -} -``` -::: - -[block-tags]: /#block-tags - -## Generating a website - -Once your code is commented, you can use the JSDoc 3 tool to generate an HTML website from your -source files. - -By default, JSDoc uses the built-in "default" template to turn the documentation into HTML. You can -edit this template to suit your own needs or create an entirely new template if that is what you -prefer. - -::: example "Running the documentation generator on the command line" - -``` -jsdoc book.js -``` -::: - -This command will create a directory named `out/` in the current working directory. Within that -directory, you will find the generated HTML pages. diff --git a/content/about-including-package.md b/content/about-including-package.md index e973a540..d7bc504a 100644 --- a/content/about-including-package.md +++ b/content/about-including-package.md @@ -1,6 +1,7 @@ --- title: Including a Package File tags: gettingStarted +layout: index.njk --- Package files contain information that can be useful for your project's documentation, such as diff --git a/content/about-including-readme.md b/content/about-including-readme.md index 3e90d227..45099045 100644 --- a/content/about-including-readme.md +++ b/content/about-including-readme.md @@ -1,6 +1,7 @@ --- title: Including a README File tags: gettingStarted +layout: index.njk --- There are two ways to incorporate a `README` file into your documentation: diff --git a/content/about-license-jsdoc3.md b/content/about-license-jsdoc3.md index 070f5ebf..c654f8c5 100644 --- a/content/about-license-jsdoc3.md +++ b/content/about-license-jsdoc3.md @@ -1,6 +1,7 @@ --- title: License tags: gettingStarted +layout: index.njk --- JSDoc is free software, licensed under the [Apache License, Version 2.0][apache-license]. Commercial diff --git a/content/about-namepaths.md b/content/about-namepaths.md index ed955aff..cbb40d5f 100644 --- a/content/about-namepaths.md +++ b/content/about-namepaths.md @@ -1,13 +1,12 @@ --- title: Using namepaths with JSDoc tags: gettingStarted +layout: index.njk related: - /about-block-inline-tags - /tags-inline-link --- -## Namepaths in JSDoc - When referring to a JavaScript variable that is elsewhere in your documentation, you must provide a unique identifier that maps to that variable. A namepath provides a way to do so and disambiguate between instance members, static members and inner variables. ::: example "Basic Syntax Examples of Namepaths in JSDoc" diff --git a/content/about-plugins.md b/content/about-plugins.md index f1f56120..e8820635 100644 --- a/content/about-plugins.md +++ b/content/about-plugins.md @@ -1,6 +1,7 @@ --- title: About JSDoc plugins tags: gettingStarted +layout: index.njk --- ## Creating and Enabling a Plugin diff --git a/content/about-tutorials.md b/content/about-tutorials.md index 981d32ba..0d46a55c 100644 --- a/content/about-tutorials.md +++ b/content/about-tutorials.md @@ -1,6 +1,7 @@ --- title: Tutorials tags: gettingStarted +layout: index.njk --- JSDoc allows you to include tutorials alongside your API documentation. You can use this feature to diff --git a/content/data/redirects.yaml b/content/data/redirects.yaml index 0a815506..a910a490 100644 --- a/content/data/redirects.yaml +++ b/content/data/redirects.yaml @@ -7,3 +7,16 @@ redirects: to: /tags-inline-link - from: /tags-method to: /tags-function + + +# --- +# toc: +# - section: "Introduction" +# generated: "introduction" +# - section: "Other Section" +# contents: +# - title: "Subsection 1" +# path: "/other-section/#subsection-1" +# - title: "Subsection 2" +# path: "/other-section/#subsection-2" +# --- \ No newline at end of file diff --git a/content/howto-amd-modules.md b/content/howto-amd-modules.md index 53f4ea68..f390dfbd 100644 --- a/content/howto-amd-modules.md +++ b/content/howto-amd-modules.md @@ -1,5 +1,6 @@ --- title: AMD Modules +layout: index.njk related: - /about-namepaths - /tags-exports diff --git a/content/howto-commonjs-modules.md b/content/howto-commonjs-modules.md index 874fb7d6..337680a6 100644 --- a/content/howto-commonjs-modules.md +++ b/content/howto-commonjs-modules.md @@ -1,5 +1,6 @@ --- title: CommonJS Modules +layout: index.njk related: - /about-namepaths - /tags-exports diff --git a/content/howto-es2015-classes.md b/content/howto-es2015-classes.md index 88f78321..ee66284e 100644 --- a/content/howto-es2015-classes.md +++ b/content/howto-es2015-classes.md @@ -1,5 +1,6 @@ --- title: ES 2015 Classes +layout: index.njk related: - /tags-augments --- diff --git a/content/howto-es2015-modules.md b/content/howto-es2015-modules.md index 8ed89bc5..5d60038a 100644 --- a/content/howto-es2015-modules.md +++ b/content/howto-es2015-modules.md @@ -1,5 +1,6 @@ --- title: ES 2015 Modules +layout: index.njk related: - /about-namepaths - /tags-module diff --git a/content/includes/index.njk b/content/includes/index.njk index 52138d4b..4f13fb40 100644 --- a/content/includes/index.njk +++ b/content/includes/index.njk @@ -9,16 +9,14 @@ {%- endmacro -%} {%- macro generateSection(tocSection) -%} -
+
+ {%- endmacro -%} {%- macro renderSection(tocSection) -%} @@ -26,12 +24,11 @@ {%- if tocSection.generated -%} {{ generateSection(tocSection) }} {%- else -%} -
+
+ {%- endif -%} {%- endmacro -%} @@ -44,12 +41,35 @@ {%- endif -%} {%- endmacro -%} + {%- block content -%} - {%- for tocSection in toc -%} - {{- renderSection(tocSection) -}} - {%- endfor -%} - -

- Fork me on GitHub -

-{% endblock %} + + +
+ {% if title -%} +

{{ title }}

+ {%- endif %} + + {{ content | safe }} + + {%- if related | length -%} + {%- set relatedLinks = related | relatedList(collections) -%} + + + {%- endif -%} + + +

+ Fork me on
GitHub +

+
+{% endblock %} \ No newline at end of file diff --git a/content/includes/layout.njk b/content/includes/layout.njk index 1fae0d6c..eb1c8786 100644 --- a/content/includes/layout.njk +++ b/content/includes/layout.njk @@ -25,13 +25,16 @@
@use JSDoc -
-
- {% if title -%} -

{{ title }}

- {%- endif %} +
+
+ +
+ +
+ +
{%- block synonyms -%} {%- if synonyms | length -%}

Synonyms

@@ -44,20 +47,9 @@ {%- endblock -%} {%- block content -%} - {{ content | safe }} + {%- endblock -%} - - {%- if related | length -%} - {%- set relatedLinks = related | relatedList(collections) -%} - - - {%- endif -%} - -
+ + + {%- block script -%} + + + + {%- endblock -%} diff --git a/content/index.md b/content/index.md index 05da2e5e..6adb3192 100644 --- a/content/index.md +++ b/content/index.md @@ -1,5 +1,85 @@ --- -title: Index -description: Official documentation for JSDoc. +title: Getting Started with JSDoc 3 +tags: gettingStarted layout: index.njk --- + + +JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You +add documentation comments directly to your source code, right alongside the code itself. The JSDoc +tool will scan your source code and generate an HTML documentation website for you. + +## Adding documentation comments to your code + +JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that +you will want to document things like modules, namespaces, classes, methods, method parameters, and +so on. + +JSDoc comments should generally be placed immediately before the code being documented. Each comment +must start with a `/**` sequence in order to be recognized by the JSDoc parser. Comments beginning +with `/*`, `/***`, or more than 3 stars will be ignored. This is a feature to allow you to suppress +parsing of comment blocks. + +::: example "The simplest documentation is just a description" + +```js +/** This is a description of the foo function. */ +function foo() { +} +``` +::: + +Adding a description is simple—just type the description you want in the documentation comment. + +Special "JSDoc tags" can be used to give more information. For example, if the function is a +constructor for a class, you can indicate this by adding a `@constructor` tag. + +::: example "Use a JSDoc tag to describe your code" + +```js +/** + * Represents a book. + * @constructor + */ +function Book(title, author) { +} +``` +::: + +More tags can be used to add more information. See the [home page][block-tags] for a complete list +of tags that are recognized by JSDoc 3. + +::: example "Adding more information with tags" + +```js +/** + * Represents a book. + * @constructor + * @param {string} title - The title of the book. + * @param {string} author - The author of the book. + */ +function Book(title, author) { +} +``` +::: + +[block-tags]: /#block-tags + +## Generating a website + +Once your code is commented, you can use the JSDoc 3 tool to generate an HTML website from your +source files. + +By default, JSDoc uses the built-in "default" template to turn the documentation into HTML. You can +edit this template to suit your own needs or create an entirely new template if that is what you +prefer. + +::: example "Running the documentation generator on the command line" + +``` +jsdoc book.js +``` +::: + +This command will create a directory named `out/` in the current working directory. Within that +directory, you will find the generated HTML pages. diff --git a/content/plugins-markdown.md b/content/plugins-markdown.md index dd3043ef..db165aa4 100644 --- a/content/plugins-markdown.md +++ b/content/plugins-markdown.md @@ -1,6 +1,7 @@ --- title: Using the Markdown plugin tags: gettingStarted +layout: index.njk --- ## Overview diff --git a/content/tags-abstract.md b/content/tags-abstract.md index 75246f6f..07dde456 100644 --- a/content/tags-abstract.md +++ b/content/tags-abstract.md @@ -1,6 +1,8 @@ --- +title: '@abstract' tag: abstract tags: blockTags +layout: index.njk description: This member must be implemented (or overridden) by the inheritor. synonyms: - virtual @@ -8,7 +10,7 @@ synonyms: ## Overview -The @abstract tag identifies members that must be implemented (or overridden) by objects that +The `@abstract` tag identifies members that must be implemented (or overridden) by objects that inherit the member. ## Example diff --git a/content/tags-access.md b/content/tags-access.md index 40f254d2..7ea3995f 100644 --- a/content/tags-access.md +++ b/content/tags-access.md @@ -1,6 +1,8 @@ --- +title: '@access' tag: access tags: blockTags +layout: index.njk description: Specify the access level of this member (private, package-private, public, or protected). related: - /tags-global diff --git a/content/tags-alias.md b/content/tags-alias.md index 4a9f0fe1..6197d8e4 100644 --- a/content/tags-alias.md +++ b/content/tags-alias.md @@ -1,6 +1,8 @@ --- +title: '@alias' tag: alias tags: blockTags +layout: index.njk description: Treat a member as if it had a different name. related: - /tags-name diff --git a/content/tags-async.md b/content/tags-async.md index 852ea30f..ce36a8f0 100644 --- a/content/tags-async.md +++ b/content/tags-async.md @@ -1,6 +1,8 @@ --- +title: '@async' tag: async tags: blockTags +layout: index.njk description: Indicate that a function is asynchronous. --- diff --git a/content/tags-augments.md b/content/tags-augments.md index 232a2716..3069fe50 100644 --- a/content/tags-augments.md +++ b/content/tags-augments.md @@ -1,6 +1,8 @@ --- +title: '@arguments' tag: augments tags: blockTags +layout: index.njk description: Indicate that a symbol inherits from, and adds to, a parent symbol. synonyms: - extends diff --git a/content/tags-author.md b/content/tags-author.md index b603df1e..c15bef7c 100644 --- a/content/tags-author.md +++ b/content/tags-author.md @@ -1,6 +1,8 @@ --- +title: '@author' tag: author tags: blockTags +layout: index.njk description: Identify the author of an item. related: - /tags-file diff --git a/content/tags-borrows.md b/content/tags-borrows.md index d097c9fb..f439e662 100644 --- a/content/tags-borrows.md +++ b/content/tags-borrows.md @@ -1,6 +1,8 @@ --- +title: '@borrows' tag: borrows tags: blockTags +layout: index.njk description: This object uses something from another object. --- diff --git a/content/tags-callback.md b/content/tags-callback.md index 3fde124d..9a3a0d14 100644 --- a/content/tags-callback.md +++ b/content/tags-callback.md @@ -1,6 +1,8 @@ --- +title: '@callback' tag: callback tags: blockTagss +layout: index.njk description: Document a callback function. related: - /tags-function diff --git a/content/tags-class.md b/content/tags-class.md index 748610f3..1b297569 100644 --- a/content/tags-class.md +++ b/content/tags-class.md @@ -1,6 +1,8 @@ --- +title: '@class' tag: class tags: blockTags +layout: index.njk description: This function is intended to be called with the "new" keyword. synonyms: - constructor diff --git a/content/tags-classdesc.md b/content/tags-classdesc.md index 110d11d9..4ae6ce39 100644 --- a/content/tags-classdesc.md +++ b/content/tags-classdesc.md @@ -1,6 +1,8 @@ --- +title: '@classdesc' tag: classdesc tags: blockTags +layout: index.njk description: Use the following text to describe the entire class. related: - /tags-class diff --git a/content/tags-constant.md b/content/tags-constant.md index b8a0c030..44b3b269 100644 --- a/content/tags-constant.md +++ b/content/tags-constant.md @@ -1,6 +1,8 @@ --- +title: '@constant' tag: constant tags: blockTags +layout: index.njk description: Document an object as a constant. synonyms: - const diff --git a/content/tags-constructs.md b/content/tags-constructs.md index c01abe56..0345f25e 100644 --- a/content/tags-constructs.md +++ b/content/tags-constructs.md @@ -1,6 +1,8 @@ --- +title: '@constructs' tag: constructs tags: blockTags +layout: index.njk description: This function member will be the constructor for the previous class. related: - /tags-lends diff --git a/content/tags-copyright.md b/content/tags-copyright.md index dc314ad9..4a9f9914 100644 --- a/content/tags-copyright.md +++ b/content/tags-copyright.md @@ -1,6 +1,8 @@ --- +title: '@copyright' tag: copyright tags: blockTags +layout: index.njk description: Document some copyright information. related: - /tags-file diff --git a/content/tags-default.md b/content/tags-default.md index 5c27098b..e3467353 100644 --- a/content/tags-default.md +++ b/content/tags-default.md @@ -1,6 +1,8 @@ --- +title: '@default' tag: default tags: blockTags +layout: index.njk description: Document the default value. synonyms: - defaultvalue diff --git a/content/tags-deprecated.md b/content/tags-deprecated.md index 13ef4a76..ed883bc9 100644 --- a/content/tags-deprecated.md +++ b/content/tags-deprecated.md @@ -1,6 +1,8 @@ --- +title: '@deprecated' tag: deprecated tags: blockTags +layout: index.njk description: Document that this is no longer the preferred way. --- diff --git a/content/tags-description.md b/content/tags-description.md index 56bb4da3..9183a50c 100644 --- a/content/tags-description.md +++ b/content/tags-description.md @@ -1,6 +1,8 @@ --- +title: '@description' tag: description tags: blockTags +layout: index.njk description: Describe a symbol. synonyms: - desc diff --git a/content/tags-enum.md b/content/tags-enum.md index 7c4e3187..81fb7bc8 100644 --- a/content/tags-enum.md +++ b/content/tags-enum.md @@ -1,6 +1,8 @@ --- +title: '@enum' tag: enum tags: blockTags +layout: index.njk description: Document a collection of related properties. related: - /tags-property diff --git a/content/tags-event.md b/content/tags-event.md index 17af1080..d0b8d65a 100644 --- a/content/tags-event.md +++ b/content/tags-event.md @@ -1,6 +1,8 @@ --- +title: '@event' tag: event tags: blockTags +layout: index.njk description: Document an event. related: - /tags-fires diff --git a/content/tags-example.md b/content/tags-example.md index 3fab33eb..5b4906a2 100644 --- a/content/tags-example.md +++ b/content/tags-example.md @@ -1,6 +1,8 @@ --- +title: '@example' tag: example tags: blockTags +layout: index.njk description: Provide an example of how to use a documented item. --- diff --git a/content/tags-exports.md b/content/tags-exports.md index 1c384b6e..9ad55864 100644 --- a/content/tags-exports.md +++ b/content/tags-exports.md @@ -1,6 +1,8 @@ --- +title: '@exports' tag: exports tags: blockTags +layout: index.njk description: Identify the member that is exported by a JavaScript module. related: - /tags-module diff --git a/content/tags-external.md b/content/tags-external.md index e0a061d1..b097687a 100644 --- a/content/tags-external.md +++ b/content/tags-external.md @@ -1,6 +1,8 @@ --- +title: '@external' tag: external tags: blockTags +layout: index.njk description: Identifies an external class, namespace, or module. synonyms: - host diff --git a/content/tags-file.md b/content/tags-file.md index a0d8469a..4c1c1af0 100644 --- a/content/tags-file.md +++ b/content/tags-file.md @@ -1,6 +1,8 @@ --- +title: '@file' tag: file tags: blockTags +layout: index.njk description: Describe a file. synonyms: - fileoverview diff --git a/content/tags-fires.md b/content/tags-fires.md index 4a1d05a4..fb6ee637 100644 --- a/content/tags-fires.md +++ b/content/tags-fires.md @@ -1,6 +1,8 @@ --- +title: '@fires' tag: fires tags: blockTags +layout: index.njk description: Describe the events this method may fire. synonyms: - emits diff --git a/content/tags-function.md b/content/tags-function.md index d875a83a..ac247973 100644 --- a/content/tags-function.md +++ b/content/tags-function.md @@ -1,6 +1,8 @@ --- +title: '@function' tag: function tags: blockTags +layout: index.njk description: Describe a function or method. synonyms: - func diff --git a/content/tags-generator.md b/content/tags-generator.md index 5ad2901f..a21ad52f 100644 --- a/content/tags-generator.md +++ b/content/tags-generator.md @@ -1,6 +1,8 @@ --- +title: '@generator' tag: generator tags: blockTags +layout: index.njk description: Indicate that a function is a generator function. --- diff --git a/content/tags-global.md b/content/tags-global.md index 8e9323cd..cb74ff10 100644 --- a/content/tags-global.md +++ b/content/tags-global.md @@ -1,6 +1,8 @@ --- +title: '@global' tag: global tags: blockTags +layout: index.njk description: Document a global object. related: - /tags-inner @@ -11,14 +13,14 @@ related: ## Overview -The @global tag specifies that a symbol should appear in the documentation as a _global_ symbol. +The `@global` tag specifies that a symbol should appear in the documentation as a _global_ symbol. JSDoc ignores the symbol's actual scope within the source file. This tag is especially useful for symbols that are defined locally, then assigned to a global symbol. ## Examples -Use the @global tag to specify that a symbol should be documented as global. +Use the `@global` tag to specify that a symbol should be documented as global. ::: example "Document an inner variable as a global" diff --git a/content/tags-hideconstructor.md b/content/tags-hideconstructor.md index cb505dce..a0cf76ff 100644 --- a/content/tags-hideconstructor.md +++ b/content/tags-hideconstructor.md @@ -1,6 +1,8 @@ --- +title: '@hideconstructor' tag: hideconstructor tags: blockTags +layout: index.njk description: Indicate that the constructor should not be displayed. related: - /tags-class diff --git a/content/tags-ignore.md b/content/tags-ignore.md index d4ddddaa..eef5007a 100644 --- a/content/tags-ignore.md +++ b/content/tags-ignore.md @@ -1,6 +1,8 @@ --- +title: '@ignore' tag: ignore tags: blockTags +layout: index.njk description: Omit a symbol from the documentation. --- diff --git a/content/tags-implements.md b/content/tags-implements.md index 47cafe48..2f647a7f 100644 --- a/content/tags-implements.md +++ b/content/tags-implements.md @@ -1,6 +1,8 @@ --- +title: '@implements' tag: implements tags: blockTags +layout: index.njk description: This symbol implements an interface. version: '>=3.3.0' related: diff --git a/content/tags-inheritdoc.md b/content/tags-inheritdoc.md index e76d0627..efd8345a 100644 --- a/content/tags-inheritdoc.md +++ b/content/tags-inheritdoc.md @@ -1,6 +1,8 @@ --- +title: '@inheritdoc' tag: inheritdoc tags: blockTags +layout: index.njk description: Indicate that a symbol should inherit its parent's documentation. version: '>=3.3.0' related: diff --git a/content/tags-inline-link.md b/content/tags-inline-link.md index 63efcb39..77885378 100644 --- a/content/tags-inline-link.md +++ b/content/tags-inline-link.md @@ -1,6 +1,8 @@ --- +title: '@link' tag: link tags: inlineTags +layout: index.njk description: Link to another item in the documentation. version: '>=3.0.0' synonyms: @@ -13,10 +15,10 @@ related: ## Syntax - {@link namepathOrURL} - [link text]{@link namepathOrURL} - {@link namepathOrURL|link text} - {@link namepathOrURL link text (after the first space)} + - `{@link namepathOrURL}` + - `[link text]{@link namepathOrURL}` + - `{@link namepathOrURL|link text}` + - `{@link namepathOrURL link text (after the first space)}` ## Overview diff --git a/content/tags-inline-tutorial.md b/content/tags-inline-tutorial.md index 2121afd1..8a3578fb 100644 --- a/content/tags-inline-tutorial.md +++ b/content/tags-inline-tutorial.md @@ -1,6 +1,8 @@ --- +title: '@tutorial' tag: tutorial tags: inlineTags +layout: index.njk description: Link to a tutorial. version: '>=3.0.0' related: @@ -9,10 +11,10 @@ related: ## Syntax - {@tutorial tutorialID} - [link text]{@tutorial tutorialID} - {@tutorial tutorialID|link text} - {@tutorial tutorialID link text (after the first space)} + - `{@tutorial tutorialID}` + - `[link text]{@tutorial tutorialID}` + - `{@tutorial tutorialID|link text}` + - `{@tutorial tutorialID link text (after the first space)}` ## Overview diff --git a/content/tags-inner.md b/content/tags-inner.md index 4ccbeb7f..28da7b7c 100644 --- a/content/tags-inner.md +++ b/content/tags-inner.md @@ -1,6 +1,8 @@ --- +title: '@inner' tag: inner tags: blockTags +layout: index.njk description: Document an inner object. related: - /tags-global @@ -10,10 +12,10 @@ related: ## Overview -Using the @inner tag will mark a symbol as an inner member of its parent symbol. This means it can +Using the `@inner` tag will mark a symbol as an inner member of its parent symbol. This means it can be referred to by "Parent~Child". -Using @inner will override a doclet's default scope (unless it is in the global scope, in which case +Using `@inner` will override a doclet's default scope (unless it is in the global scope, in which case it will remain global). @@ -32,8 +34,8 @@ it will remain global). ``` ::: -Note that in the above we could have used "@function MyNamespace~myFunction" instead of the -@memberof and @inner tags. +Note that in the above we could have used `@function MyNamespace~myFunction` instead of the +`@memberof` and `@inner` tags. ::: example "Using @inner" diff --git a/content/tags-instance.md b/content/tags-instance.md index 574dad93..1905ad22 100644 --- a/content/tags-instance.md +++ b/content/tags-instance.md @@ -1,6 +1,8 @@ --- +title: '@instance' tag: instance tags: blockTags +layout: index.njk description: Document an instance member. related: - /tags-global @@ -10,16 +12,16 @@ related: ## Overview -Using the @instance tag will mark a symbol as an instance member of its parent symbol. This means it +Using the `@instance` tag will mark a symbol as an instance member of its parent symbol. This means it can be referred to by "Parent#Child". -Using @instance will override a doclet's default scope (unless it is in the global scope, in which +Using `@instance` will override a doclet's default scope (unless it is in the global scope, in which case it will remain global). ## Examples -The following example is a longhand way of writing "@function MyNamespace#myFunction": +The following example is a longhand way of writing `@function MyNamespace#myFunction`: ::: example "Using @instance to make a virtual doclet an instance member" diff --git a/content/tags-interface.md b/content/tags-interface.md index 1eba8116..31158151 100644 --- a/content/tags-interface.md +++ b/content/tags-interface.md @@ -1,6 +1,8 @@ --- +title: '@interface' tag: interface tags: blockTags +layout: index.njk description: This symbol is an interface that others can implement. version: '>=3.3.0' related: diff --git a/content/tags-kind.md b/content/tags-kind.md index 7639612a..d4d32642 100644 --- a/content/tags-kind.md +++ b/content/tags-kind.md @@ -1,6 +1,8 @@ --- +title: '@kind' tag: kind tags: blockTags +layout: index.njk description: What kind of symbol is this? related: - /tags-type @@ -27,12 +29,12 @@ where `` is one of: ## Overview -The @kind tag is used to document what _kind_ of symbol is being documented (for example, a class or +The `@kind` tag is used to document what _kind_ of symbol is being documented (for example, a class or a module). The _kind_ of symbol differs from a symbol's _type_ (for example, string or boolean). -Usually you do not need the @kind tag, because the symbol's kind is determined by other tags in the -doclet. For example, using the @class tag automatically implies "@kind class", and using the -@namespace tag implies "@kind namespace". +Usually you do not need the `@kind` tag, because the symbol's kind is determined by other tags in the +doclet. For example, using the `@class` tag automatically implies "@kind class", and using the +`@namespace` tag implies "@kind namespace". ## Examples diff --git a/content/tags-lends.md b/content/tags-lends.md index 200b4ed4..ebf1a760 100644 --- a/content/tags-lends.md +++ b/content/tags-lends.md @@ -1,6 +1,8 @@ --- +title: '@lends' tag: lends tags: blockTags +layout: index.njk description: Document properties on an object literal as if they belonged to a symbol with a given name. related: - /tags-borrows diff --git a/content/tags-license.md b/content/tags-license.md index 351e3d16..ecaa0d61 100644 --- a/content/tags-license.md +++ b/content/tags-license.md @@ -1,6 +1,8 @@ --- +title: '@license' tag: license tags: blockTags +layout: index.njk description: Identify the license that applies to this code. --- diff --git a/content/tags-listens.md b/content/tags-listens.md index 7e2fdf83..af18d30d 100644 --- a/content/tags-listens.md +++ b/content/tags-listens.md @@ -1,6 +1,8 @@ --- +title: '@listens' tag: listens tags: blockTags +layout: index.njk description: List the events that a symbol listens for. related: - /tags-event diff --git a/content/tags-member.md b/content/tags-member.md index 617157b1..369ac88c 100644 --- a/content/tags-member.md +++ b/content/tags-member.md @@ -1,6 +1,8 @@ --- +title: '@member' tag: member tags: blockTags +layout: index.njk description: Document a member. synonyms: - var diff --git a/content/tags-memberof.md b/content/tags-memberof.md index 214cb9fe..44fba8d7 100644 --- a/content/tags-memberof.md +++ b/content/tags-memberof.md @@ -1,6 +1,8 @@ --- +title: '@memberof' tag: memberof tags: blockTags +layout: index.njk description: This symbol belongs to a parent symbol. related: - /tags-name diff --git a/content/tags-mixes.md b/content/tags-mixes.md index 6a005e03..8ffd26e9 100644 --- a/content/tags-mixes.md +++ b/content/tags-mixes.md @@ -1,6 +1,8 @@ --- +title: '@mixes' tag: mixes tags: blockTags +layout: index.njk description: This object mixes in all the members from another object. related: - /tags-borrows diff --git a/content/tags-mixin.md b/content/tags-mixin.md index 23c12e5c..2cb70056 100644 --- a/content/tags-mixin.md +++ b/content/tags-mixin.md @@ -1,6 +1,8 @@ --- +title: '@mixin' tag: mixin tags: blockTags +layout: index.njk description: Document a mixin object. related: - /tags-borrows diff --git a/content/tags-module.md b/content/tags-module.md index 3874cea2..0d81a6c6 100644 --- a/content/tags-module.md +++ b/content/tags-module.md @@ -1,6 +1,8 @@ --- +title: '@module' tag: module tags: blockTags +layout: index.njk description: Document a JavaScript module. related: - /tags-exports diff --git a/content/tags-name.md b/content/tags-name.md index f069aad0..14adb5a7 100644 --- a/content/tags-name.md +++ b/content/tags-name.md @@ -1,6 +1,8 @@ --- +title: '@name' tag: name tags: blockTags +layout: index.njk description: Document the name of an object. related: - /about-namepaths @@ -13,11 +15,11 @@ related: ## Overview -The @name tag forces JSDoc to associate the remainder of the JSDoc comment with the given name, +The `@name` tag forces JSDoc to associate the remainder of the JSDoc comment with the given name, ignoring all surrounding code. This tag is best used in "virtual comments" for symbols that are not readily visible in the code, such as methods that are generated at runtime. -When you use the @name tag, you must provide additional tags that tell JSDoc what kind of symbol you +When you use the `@name` tag, you must provide additional tags that tell JSDoc what kind of symbol you are documenting; whether the symbol is a member of another symbol; and so on. If you do not provide this information, the symbol will not be documented correctly. diff --git a/content/tags-namespace.md b/content/tags-namespace.md index c823dfcb..11e7bcb0 100644 --- a/content/tags-namespace.md +++ b/content/tags-namespace.md @@ -1,6 +1,8 @@ --- +title: '@namespace' tag: namespace tags: blockTags +layout: index.njk description: Document a namespace object. related: - /tags-module @@ -13,11 +15,11 @@ related: ## Overview -The @namespace tag indicates that an object creates a namespace for its members. You can also write +The `@namespace` tag indicates that an object creates a namespace for its members. You can also write a virtual JSDoc comment that defines a namespace used by your code. If a namespace is defined by a symbol other than an object literal, you can include a type -expression along with the @namespace tag. If the @namespace tag includes a type, it must also +expression along with the @namespace tag. If the `@namespace` tag includes a type, it must also include a name. You may need to document a namespace whose name includes unusual characters, such as "#" or "!". In @@ -59,7 +61,7 @@ var MyNamespace = { ``` ::: -If a @namespace includes a symbol whose name has unusual characters, you must enclose the symbol's +If a `@namespace` includes a symbol whose name has unusual characters, you must enclose the symbol's name in double quotes. If the symbol's name already contains one or more double quotes, escape the double quotes with a leading backslash (\\). diff --git a/content/tags-override.md b/content/tags-override.md index 05ccb2a9..d9f6f0f4 100644 --- a/content/tags-override.md +++ b/content/tags-override.md @@ -1,6 +1,8 @@ --- +title: '@override' tag: override tags: blockTags +layout: index.njk description: Indicate that a symbol overrides its parent. dictionaries: - closure diff --git a/content/tags-package.md b/content/tags-package.md index 8df52743..0362f602 100644 --- a/content/tags-package.md +++ b/content/tags-package.md @@ -1,6 +1,8 @@ --- +title: '@package' tag: package tags: blockTags +layout: index.njk description: This symbol is meant to be package-private. related: - /tags-access diff --git a/content/tags-param.md b/content/tags-param.md index e2565fc0..27ad8b2c 100644 --- a/content/tags-param.md +++ b/content/tags-param.md @@ -1,6 +1,8 @@ --- +title: '@param' tag: param tags: blockTags +layout: index.njk description: Document the parameter to a function. synonyms: - arg diff --git a/content/tags-private.md b/content/tags-private.md index 5b66e87a..d2254373 100644 --- a/content/tags-private.md +++ b/content/tags-private.md @@ -1,6 +1,8 @@ --- +title: '@private' tag: private tags: blockTags +layout: index.njk description: This symbol is meant to be private. related: - /tags-access diff --git a/content/tags-property.md b/content/tags-property.md index 946e3fda..f4f265f1 100644 --- a/content/tags-property.md +++ b/content/tags-property.md @@ -1,6 +1,8 @@ --- +title: '@property' tag: property tags: blockTags +layout: index.njk description: Document a property of an object. synonyms: - prop diff --git a/content/tags-protected.md b/content/tags-protected.md index 49a3aeb4..e366af8c 100644 --- a/content/tags-protected.md +++ b/content/tags-protected.md @@ -1,6 +1,8 @@ --- +title: '@protected' tag: protected tags: blockTags +layout: index.njk description: This symbol is meant to be protected. related: - /tags-access diff --git a/content/tags-public.md b/content/tags-public.md index 6b5ccc52..4dc64888 100644 --- a/content/tags-public.md +++ b/content/tags-public.md @@ -1,6 +1,8 @@ --- +title: '@public' tag: public tags: blockTags +layout: index.njk description: This symbol is meant to be public. related: - /tags-access diff --git a/content/tags-readonly.md b/content/tags-readonly.md index 4188915b..b3aadb67 100644 --- a/content/tags-readonly.md +++ b/content/tags-readonly.md @@ -1,19 +1,21 @@ --- +title: '@readonly' tag: readonly tags: blockTags +layout: index.njk description: This symbol is meant to be read-only. --- ## Overview -The @readonly tag indicates that a symbol is intended to be read-only. Note this is for the purpose +The `@readonly` tag indicates that a symbol is intended to be read-only. Note this is for the purpose of documentation only - JSDoc won't check whether you've _actually_ treated the symbol as read-only in your code. ## Examples -::: example "Using the @readonly tag" +::: example "Using the `@readonly` tag" ```js /** diff --git a/content/tags-requires.md b/content/tags-requires.md index eb9eeb2c..d4e406a0 100644 --- a/content/tags-requires.md +++ b/content/tags-requires.md @@ -1,6 +1,8 @@ --- +title: '@requires' tag: requires tags: blockTags +layout: index.njk description: This file requires a JavaScript module. --- @@ -10,8 +12,8 @@ description: This file requires a JavaScript module. ## Overview -The @requires tag allows you to document that a module is needed to use this code. A JSDoc comment -can have multiple @require tags. The module name can be specified as "moduleName" or +The `@requires` tag allows you to document that a module is needed to use this code. A JSDoc comment +can have multiple `@requires` tags. The module name can be specified as "moduleName" or "module:moduleName"; both forms will be interpreted as modules. JSDoc does not attempt to process the module that is being included. If you want the module to be diff --git a/content/tags-returns.md b/content/tags-returns.md index f2906335..1c771c06 100644 --- a/content/tags-returns.md +++ b/content/tags-returns.md @@ -1,6 +1,8 @@ --- +title: '@returns' tag: returns tags: blockTags +layout: index.njk description: Document the return value of a function. synonyms: - return diff --git a/content/tags-see.md b/content/tags-see.md index 4727a5a9..b3a13830 100644 --- a/content/tags-see.md +++ b/content/tags-see.md @@ -1,6 +1,8 @@ --- +title: '@see' tag: see tags: blockTags +layout: index.njk description: Refer to some other documentation for more information. related: - /tags-inline-link @@ -14,7 +16,7 @@ related: ## Overview -The @see tag allows you to refer to another symbol or resource that may be related to the one being +The `@see` tag allows you to refer to another symbol or resource that may be related to the one being documented. You can provide either a symbol's namepath or free-form text. If you provide a namepath, JSDoc's default template automatically converts the namepath to a link. diff --git a/content/tags-since.md b/content/tags-since.md index 10092c9f..19286309 100644 --- a/content/tags-since.md +++ b/content/tags-since.md @@ -1,6 +1,8 @@ --- +title: '@since' tag: since tags: blockTags +layout: index.njk description: When was this feature added? related: - /tags-version @@ -13,7 +15,7 @@ related: ## Overview -The @since tag indicates that a class, method, or other symbol was added in a specific version. +The `@since` tag indicates that a class, method, or other symbol was added in a specific version. ## Examples diff --git a/content/tags-static.md b/content/tags-static.md index 1c301078..01f0cf39 100644 --- a/content/tags-static.md +++ b/content/tags-static.md @@ -1,6 +1,8 @@ --- +title: '@static' tag: static tags: blockTags +layout: index.njk description: Document a static member. related: - /tags-global @@ -10,17 +12,17 @@ related: ## Overview -The @static tag indicates that a symbol is contained within a parent and can be accessed without +The `@static` tag indicates that a symbol is contained within a parent and can be accessed without instantiating the parent. -Using the @static tag will override a symbol's default scope, with one exception: Symbols in global +Using the `@static` tag will override a symbol's default scope, with one exception: Symbols in global scope will remain global. ## Examples -The following example has the same effect as writing "@function MyNamespace.myFunction" and omitting -the @memberof and @static tags: +The following example has the same effect as writing `@function MyNamespace.myFunction` and omitting +the `@memberof` and `@static` tags: ::: example "Using @static in a virtual comment" diff --git a/content/tags-summary.md b/content/tags-summary.md index e5d67163..73fbbdf9 100644 --- a/content/tags-summary.md +++ b/content/tags-summary.md @@ -1,6 +1,8 @@ --- +title: '@summary' tag: summary tags: blockTags +layout: index.njk description: A shorter version of the full description. related: - /tags-classdesc @@ -14,7 +16,7 @@ related: ## Overview -The @summary tag is a shorter version of the full description. It can be added to any doclet. +The `@summary` tag is a shorter version of the full description. It can be added to any doclet. ## Examples diff --git a/content/tags-this.md b/content/tags-this.md index 2358ad01..a5b96b57 100644 --- a/content/tags-this.md +++ b/content/tags-this.md @@ -1,6 +1,8 @@ --- +title: '@this' tag: this tags: blockTags +layout: index.njk description: What does the 'this' keyword refer to here? related: - /tags-memberof @@ -13,12 +15,12 @@ related: ## Overview -The @this tag indicates what the `this` keyword refers to when used within another symbol. +The `@this` tag indicates what the `this` keyword refers to when used within another symbol. ## Examples -In the following example, the @this tag causes "this.name" to be documented as "Greeter#name" +In the following example, the `@this` tag causes `this.name` to be documented as `Greeter#name` rather than a global symbol called "name". ```js diff --git a/content/tags-throws.md b/content/tags-throws.md index 09be0c1a..39ceb035 100644 --- a/content/tags-throws.md +++ b/content/tags-throws.md @@ -1,6 +1,8 @@ --- +title: '@throws' tag: throws tags: blockTags +layout: index.njk description: Describe what errors could be thrown. synonyms: - exception @@ -15,8 +17,8 @@ synonyms: ## Overview -The @throws tag allows you to document an error that a function might throw. You can include the -@throws tag more than once in a single JSDoc comment. +The `@throws` tag allows you to document an error that a function might throw. You can include the +`@throws` tag more than once in a single JSDoc comment. ## Examples diff --git a/content/tags-todo.md b/content/tags-todo.md index cc18a3f4..043077bb 100644 --- a/content/tags-todo.md +++ b/content/tags-todo.md @@ -1,6 +1,8 @@ --- +title: '@todo' tag: todo tags: blockTags +layout: index.njk description: Document tasks to be completed. --- @@ -11,8 +13,8 @@ description: Document tasks to be completed. ## Overview -The @todo tag allows you to document tasks to be completed for some part of your code. You can use -the @todo tag more than once in a single JSDoc comment. +The `@todo` tag allows you to document tasks to be completed for some part of your code. You can use +the `@todo` tag more than once in a single JSDoc comment. ## Examples diff --git a/content/tags-tutorial.md b/content/tags-tutorial.md index 5554d8ec..95b852a6 100644 --- a/content/tags-tutorial.md +++ b/content/tags-tutorial.md @@ -1,6 +1,8 @@ --- +title: '@tutorial' tag: tutorial tags: blockTags +layout: index.njk description: Insert a link to an included tutorial file. related: - /about-tutorials @@ -10,7 +12,7 @@ related: ## Syntax - @tutorial + `@tutorial ` ## Overview diff --git a/content/tags-type.md b/content/tags-type.md index 10f6f07b..76e5981a 100644 --- a/content/tags-type.md +++ b/content/tags-type.md @@ -1,6 +1,8 @@ --- +title: '@type' tag: type tags: blockTags +layout: index.njk description: Document the type of an object. related: - /tags-callback @@ -19,7 +21,7 @@ related: ## Overview -The @type tag allows you to provide a type expression identifying the type of value that a symbol +The `@type` tag allows you to provide a type expression identifying the type of value that a symbol may contain, or the type of value returned by a function. You can also include type expressions with many other JSDoc tags, such as the [@param tag][param-tag]. diff --git a/content/tags-typedef.md b/content/tags-typedef.md index 6e7e1ccb..50be255e 100644 --- a/content/tags-typedef.md +++ b/content/tags-typedef.md @@ -1,6 +1,8 @@ --- +title: '@typedef' tag: typedef tags: blockTags +layout: index.njk description: Document a custom type. related: - /tags-callback @@ -15,7 +17,7 @@ related: ## Overview -The @typedef tag is useful for documenting custom types, particularly if you wish to refer to them +The `@typedef` tag is useful for documenting custom types, particularly if you wish to refer to them repeatedly. These types can then be used within other tags expecting a type, such as [@type][type-tag] or [@param][param-tag]. diff --git a/content/tags-variation.md b/content/tags-variation.md index ac3166de..5e72ee95 100644 --- a/content/tags-variation.md +++ b/content/tags-variation.md @@ -1,6 +1,8 @@ --- +title: '@variation' tag: variation tags: blockTags +layout: index.njk description: Distinguish different objects with the same name. related: - /tags-alias diff --git a/content/tags-version.md b/content/tags-version.md index 9b5aabdf..66b51fac 100644 --- a/content/tags-version.md +++ b/content/tags-version.md @@ -1,6 +1,8 @@ --- +title: '@version' tag: version tags: blockTags +layout: index.njk description: Documents the version number of an item. related: - /tags-since diff --git a/content/tags-yields.md b/content/tags-yields.md index 412de4ff..5e36e4be 100644 --- a/content/tags-yields.md +++ b/content/tags-yields.md @@ -1,6 +1,8 @@ --- +title: '@yields' tag: yields tags: blockTags +layout: index.njk description: Document the value yielded by a generator function. synonyms: - yield diff --git a/eleventy.config.js b/eleventy.config.js index be86c8df..3f32b470 100644 --- a/eleventy.config.js +++ b/eleventy.config.js @@ -56,6 +56,7 @@ module.exports = (eleventyConfig) => { eleventyConfig.addPassthroughCopy('./images'); eleventyConfig.addPassthroughCopy('./styles'); + eleventyConfig.addPassthroughCopy('lib'); // to execute nav-sidebar.js eleventyConfig.setLibrary('md', renderer()); eleventyConfig.setNunjucksEnvironmentOptions({ diff --git a/lib/nav-sidebar.js b/lib/nav-sidebar.js new file mode 100644 index 00000000..1d7c2054 --- /dev/null +++ b/lib/nav-sidebar.js @@ -0,0 +1,78 @@ +// client side script + +const themeChangeBtn = document.getElementById("theme-toggle-btn"); +const themeIcon = document.getElementById("theme-icon"); +const navMenu = document.querySelector(".nav-sidebar"); +const burgerIcon = document.getElementById("burger-menu"); +const closeMenuIcon = document.getElementById("closeMenuIcon"); +const currentPath = window.location.pathname; // Get the current path from the URL +const navLinks = document.querySelectorAll('.nav-sidebar a'); // Select all links in the sidebar +const article = document.querySelector('.article-content'); + + +navLinks.forEach(link => { + const linkPath = new URL(link.href).pathname; + // Check if the link path matches the current page path + if (linkPath === currentPath) { + link.classList.add('active'); // Add a class to highlight the active link + if (window.innerWidth > 768) + link.scrollIntoView({ block: 'center' }); // Only scroll to the active link and center vertically on desktop + } else { + link.classList.remove('active'); // Remove the active class from other links + } +}); + +// Checks if the site is on the index page +if (currentPath == '/') { + navLinks[0].classList.add('active'); // Adds an active state to the first link in the nav menu +} + +// Checks if the nav sidebar has been scrolled. +if (navMenu.scrollTop > 0) { + article.style.marginTop = '40px'; +} + + +let themeSwitch = '0'; // 0 - dark, 1 - light +let savedThemeChoice = localStorage.getItem("themeChoice"); + +// Check if a theme choice has been saved +if (savedThemeChoice !== null) { + if (savedThemeChoice == '0') { + themeIcon.name = "sunny"; + document.body.classList.remove("dark-mode"); + } + else if(savedThemeChoice == '1') { + themeIcon.name = "moon"; + document.body.classList.add("dark-mode"); + } +} + +if (savedThemeChoice == '1') { + themeSwitch = '1' +} +themeChangeBtn.onclick = (e) => { + // Toggle theme and update the name attribute of themeIcon + themeIcon.name = themeIcon.name == "sunny" ? "moon" : "sunny"; + // console.log(themeIcon.name) + document.body.classList.toggle("dark-mode"); + + if(themeSwitch == '0') { + themeSwitch = '1'; + } + else if(themeSwitch == '1') { + themeSwitch = '0'; + } + + localStorage.setItem("themeChoice", themeSwitch); +}; + +// open nav menu +burgerIcon.onclick=()=>{ + navMenu.classList.add("showMenu"); +} + +// close nav menu +closeMenuIcon.onclick=()=>{ + navMenu.classList.remove("showMenu"); +} \ No newline at end of file diff --git a/styles/_variables.css b/styles/_variables.css new file mode 100644 index 00000000..7b9fd1b4 --- /dev/null +++ b/styles/_variables.css @@ -0,0 +1,63 @@ +@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;700&display=swap'); + + +:root { + /* General colors */ + --Marine-blue: hsl(213, 96%, 18%); + --Purplish-blue: hsl(243, 100%, 62%); + --Pastel-blue: hsl(228, 100%, 84%); + --Light-blue: hsl(206, 94%, 87%); + --Strawberry-red: hsl(354, 84%, 57%); + --Bluish-white: #f5f8ff; + --Bluish-gray: hsl(207, 24%, 15%); + + /* Neutral colors*/ + --Cool-gray: hsl(231, 11%, 63%); + --Light-gray: hsl(229, 24%, 87%); + --Magnolia: hsl(214, 40%, 92%); + --Alabaster: hsl(231, 100%, 99%); + --White: hsl(0, 0%, 100%); + + /* Tomorrow theme colors for Highlight.js */ + /* Based on https://github.com/chriskempson/tomorrow-theme */ + --text-color: #3d3d3c; + --tomorrow-blue: #4271ae; + --tomorrow-gray: #8e908c; + --tomorrow-green: #83a303; + --tomorrow-orange: #f57a06; + --tomorrow-purple: #b476dd; + --tomorrow-red: #bc8b10; + --tomorrow-yellow: #c99e00; + + /* Fonts */ + --F-size: 14px; + --F-family:'Poppins', sans-serif; + --F-Weights: 400, 500, 700; + + /* text rendering */ + font-synthesis: none; + text-rendering: optimizeLegibility; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + scroll-behavior: smooth; + + /* Light mode */ + --bg-color: #f5f8ff; + --text-color: hsl(207, 24%, 15%); + --heading-color: hsl(213, 96%, 18%); + --heading-line: hsl(229, 24%, 87%); + --bx-shadow: hsl(229, 24%, 87%); + --code-bg: hsl(214, 40%, 92%); + --nav-link-color: hsl(210, 7%, 40%); +} + +.dark-mode{ + --bg-color: hsl(203, 19%, 13%); + --text-color: hsl(214, 40%, 92%); + --heading-color: hsl(216, 63%, 97%); + --heading-line: hsl(0, 0%, 28%); + --bx-shadow: hsl(0, 0%, 18%); + --code-bg: hsl(0, 2%, 9%); + --tomorrow-green: #97bc02; + --nav-link-color: hsl(214, 12%, 73%); +} \ No newline at end of file diff --git a/styles/css3-github-ribbon.css b/styles/css3-github-ribbon.css index 83e6a2eb..940daee4 100644 --- a/styles/css3-github-ribbon.css +++ b/styles/css3-github-ribbon.css @@ -1,2 +1,24 @@ -body{background-color:#fff} -.github-ribbon{background-color:#121621;top:3.2em;right:-3.7em;-webkit-transform:rotate(45deg);-moz-transform:rotate(45deg);transform:rotate(45deg);-webkit-box-shadow:0 0 0 1px #1d212e inset,0 0 2px 1px #fff inset,0 0 1em #888;-moz-box-shadow:0 0 0 1px #1d212e inset,0 0 2px 1px #fff inset,0 0 1em #888;box-shadow:0 0 0 1px #1d212e inset,0 0 2px 1px #fff inset,0 0 1em #888;color:rgba(255,255,255,0.90)!important;display:block;padding:.6em 3.5em;position:absolute;font:bold .82em sans-serif;text-align:center;text-decoration:none;text-shadow:1px -1px 8px rgba(0,0,0,0.60);-webkit-user-select:none;-moz-user-select:none;user-select:none} \ No newline at end of file +.github-ribbon{ + background-color:#121621; + top:2em; + right:-3.5em; + -webkit-transform:rotate(45deg); + -moz-transform:rotate(45deg); + transform:rotate(45deg); + color:rgba(255,255,255,0.90)!important; + padding:.5em 4.5em; + position:fixed; + font:bold .9em sans-serif; + text-align:center; + text-decoration:none; + -webkit-user-select:none; + -moz-user-select:none; + user-select:none; + z-index: 300; +} + +@media (max-width: 768px) { + .github-ribbon{ + font-size: .8em; + } +} \ No newline at end of file diff --git a/styles/hljs-tomorrow.css b/styles/hljs-tomorrow.css index 58123fa9..e776be2d 100644 --- a/styles/hljs-tomorrow.css +++ b/styles/hljs-tomorrow.css @@ -1,32 +1,19 @@ -/* - Copyright 2022 the JSDoc Authors. - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - https://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -*/ - -/* Tomorrow theme for Highlight.js */ -/* Based on https://github.com/chriskempson/tomorrow-theme */ - -:root { - --text-color: #3d3d3c; - --tomorrow-blue: #4271ae; - --tomorrow-gray: #8e908c; - --tomorrow-green: #718c00; - --tomorrow-orange: #f5871f; - --tomorrow-purple: #8959a8; - --tomorrow-red: #c82829; - --tomorrow-yellow: #c99e00; -} +@import url(./_variables.css); + +/* Copyright 2022 the JSDoc Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. */ + .hljs, .no-hljs { @@ -109,4 +96,4 @@ .hljs-doctag, .hljs-strong { font-weight: bold; -} +} \ No newline at end of file diff --git a/styles/usejsdoc.css b/styles/usejsdoc.css index 6c285fa2..3724f566 100644 --- a/styles/usejsdoc.css +++ b/styles/usejsdoc.css @@ -1,80 +1,143 @@ -body { - font: 1em 'Helvetica Neue', Helvetica, Arial, sans-serif; - padding: 0; +@import url(./_variables.css); + +::-webkit-scrollbar{ + width: 5px; + background-color: var(--bg-color); +} + +::-webkit-scrollbar-thumb{ + background-color: var(--text-color); + border-radius: 20px; +} + +* { margin: 0; + padding: 0; + box-sizing: border-box; } -a, a:visited, a:active { - color: #605C89; +body { + background-color: var(--bg-color); + font-family: var(--F-family); + font-size: var(--F-size); + color: var(--text-color); + position: relative; } header { - background-color: #EBEBEB; + background-color: var(--bg-color); color: #006FBB; margin: 0; - margin-bottom: 32px; - padding: 18px; + padding: 10px 16px; font-size: 2.4em; font-weight: bold; - border-bottom: 1px #C6C6C6 solid; + position: sticky; + top: 0; + z-index: 200; + display: flex; + justify-content: space-between; + box-shadow: 1px 1px 5px var(--bx-shadow); } -header a, header a:visited { - color: #006FBB; +header > a{ + color: var(--text-color); text-decoration: none; } -article { - margin: 18px; +.menu-wrapper{ + display: flex; + justify-content: space-between; + align-items: center; + margin-right: 100px; +} + +#theme-toggle-btn, #burger-menu{ + border-radius: 2px; + transition: .5s; + cursor: pointer; + color: var(--text-color); + height: 40px; +} + + +#theme-toggle-btn:hover, #burger-menu:hover, #closeMenuIcon:hover { + transform: scale(1.1); +} + +#theme-toggle-btn { + font-size: 1.1em; + padding: 5px 10px 40px; + display: grid; + place-items: center; + position: relative; + top: 1px; +} + +#burger-menu{ + margin-left: 20px; + font-size: 2em; + display: none; +} + +#closeMenuIcon{ + font-size:2.5em; + font-weight:900; + cursor: pointer; + position: sticky; + right:15px; + left: 100%; + top: 0; + display: none; + background-color: var(--bg-color); } footer { - margin: 16px; - margin-top: 32px; + padding: 22px 22px 5px; font-style: italic; - font-size: 0.8em; + font-size: 0.9em; + min-height: 100px; + color: var(--text-color); + background-color: var(--bg-color); + box-shadow: -1px -1px 5px var(--bx-shadow); + line-height: 3; +} + +a { + color: var(--tomorrow-blue) } h1, h2, h3, h4, h5, h6 { - color: #B93A38; + color: var(--heading-color); + margin: 15px 0; } h1 { - font-size: 1.428em; - text-indent: 0; + font-size: 1.9em; } h2 { - font-size: 1.285em; - text-indent: 1%; + font-size: 1.5em; } h3 { - font-size: 1.142em; - text-indent: 2%; + font-size: 1.15em; } h4 { font-size: 1em; - text-indent: 3%; } h5 { font-size: 0.857em; - text-indent: 4%; } h6 { font-size: 0.714em; - text-indent: 5%; -} - -p { - text-indent: 2%; } figure pre code { - font-size: 0.857em; + font-size: 1em; + line-height: 1; } figcaption { @@ -93,7 +156,7 @@ dt { } dt a, dt a:visited { - color: #3E00B6; + color: var(--tomorrow-purple); } dd { @@ -102,34 +165,43 @@ dd { } ol, ul { - margin-left: 2%; + margin: 15px 0 15px 20px; } -code { - font: 0.9em Consolas, "Lucida Console", Monaco, monospace; - background-color: #DEDEDE; +li { + margin: 8px 0; + line-height: 1.7; } pre { display: block; - border: 1px solid #999; - margin: 12px; - padding: 8px; + margin: 15px 0; + padding: 10px; white-space: pre-wrap; - background-color: #DEDEDE; + background-color: var(--code-bg); + line-height: 1.8; +} + +code { + font: 0.9em Consolas, "Lucida Console", Monaco, monospace; + background-color: var(--code-bg); + padding: 2px 5px; + letter-spacing: .5px; } table { border-collapse: collapse; + margin: 25px 0; } th, td { - border: 1px solid #999; + border: 1px solid var(--heading-line); + padding: 13px; } th { - background-color: #DEDEDE; - color: #B93A38; + background-color: var(--code-bg); + color: var(--heading-color); } .example dt { @@ -137,6 +209,163 @@ th { } .license-badge { - border-width: 0; + border-width: 2px; text-decoration: none; } + + +/* Main content styling */ +.main-secion { + display: flex; + flex-wrap: nowrap; + width: 100vw; + max-width: 1500px; +} + +/* Sidebar styling */ +.nav-sidebar { + min-width: 280px; + max-width: 280px; + background-color: var(--bg-color); + padding: 25px 20px; + box-shadow: 2px 0 5px rgba(0, 0, 0, 0.1); + position: sticky; + top: 68px; + height: 90vh; + overflow-y: auto; +} + +.nav-sidebar h2 { + margin: 0; + margin-bottom: 10px; +} + +.nav-sidebar > ul { + margin-bottom: 30px; + margin-left: 10px; +} + +.nav-sidebar li{ + list-style-type: none; + margin-bottom: 9px; + color: var(--Marine-blue); + cursor: pointer; +} + +.nav-sidebar li > a{ + color: var(--nav-link-color); + text-decoration: none; +} + +.nav-sidebar li > a:hover{ + color: var(--tomorrow-blue); +} + +.nav-sidebar li > a.active { + color: var(--tomorrow-orange); +} + +.article-content { + flex-grow: 1; + padding: 15px 70px 40px 40px; + min-height: 90vh; + overflow-y: auto; +} + +.article-content h1, .article-content h2 { + border-bottom: 1px solid var(--heading-line); + padding-bottom: 10px; +} + +.article-content p { + margin-bottom: 10px; + line-height: 1.8; + word-spacing: 1.3px; +} + + +/* Responsive design Mobile*/ +@media (max-width: 768px) { + body { + --F-size: 12.5px; + font-size: var(--F-size); + } + + header { + font-size: 1.6em; + padding: 10px 16px 8px; + align-items: center; + } + + #theme-toggle-btn { + font-size: 1.3em; + } + + #burger-menu{ + font-size: 1.5em; + position: relative; + bottom: 4px; + } + + #burger-menu, #closeMenuIcon{ + display: block; + } + + h1 { + font-size: 1.5em; + } + + h2 { + font-size: 1.25em; + } + + h3 { + font-size: 1.1em; + } + + h4 { + font-size: .9em; + } + + h5 { + font-size: 0.8em; + } + + h6 { + font-size: 0.7em; + } + + figure pre code { + font-size: .87em; + } + + code { + font-size: .9em; + } + + pre { + font-size: .85em; + } + + .nav-sidebar { + width: 0; + min-width: 0; + max-width: 0; + height: 100vh; + position: fixed; + top: 0; + left: 0; + z-index: 500; + padding: 0 + } + + .showMenu { + min-width: 70vw; + padding: 25px 20px; + } + + .article-content { + width: 100%; + padding-right: 45px; + } +} \ No newline at end of file From ada2c49d491fdff9abbaacc435fd93aa014af618 Mon Sep 17 00:00:00 2001 From: Sarah-okolo Date: Mon, 9 Sep 2024 12:54:29 +0100 Subject: [PATCH 2/6] update layout templates --- content/data/redirects.yaml | 15 +-------------- content/includes/index.njk | 20 +++++++++++--------- content/includes/layout.njk | 24 +++++++++++------------- 3 files changed, 23 insertions(+), 36 deletions(-) diff --git a/content/data/redirects.yaml b/content/data/redirects.yaml index a910a490..12f7f3d6 100644 --- a/content/data/redirects.yaml +++ b/content/data/redirects.yaml @@ -6,17 +6,4 @@ redirects: - from: /tags-link to: /tags-inline-link - from: /tags-method - to: /tags-function - - -# --- -# toc: -# - section: "Introduction" -# generated: "introduction" -# - section: "Other Section" -# contents: -# - title: "Subsection 1" -# path: "/other-section/#subsection-1" -# - title: "Subsection 2" -# path: "/other-section/#subsection-2" -# --- \ No newline at end of file + to: /tags-function \ No newline at end of file diff --git a/content/includes/index.njk b/content/includes/index.njk index 4f13fb40..2baeddc7 100644 --- a/content/includes/index.njk +++ b/content/includes/index.njk @@ -43,17 +43,20 @@ {%- block content -%} - - -
{% if title -%}

{{ title }}

{%- endif %} + + {%- block synonyms -%} + {%- if synonyms | length -%} +

Synonyms

+
    + {% for synonym in synonyms -%} +
  • {{ synonym }}
    • + {%- endfor %} +
+ {%- endif -%} + {%- endblock -%} {{ content | safe }} @@ -71,5 +74,4 @@

Fork me on
GitHub

-
{% endblock %} \ No newline at end of file diff --git a/content/includes/layout.njk b/content/includes/layout.njk index eb1c8786..0bfdd13a 100644 --- a/content/includes/layout.njk +++ b/content/includes/layout.njk @@ -35,20 +35,18 @@
- {%- block synonyms -%} - {%- if synonyms | length -%} -

Synonyms

-
    - {% for synonym in synonyms -%} -
  • {{ synonym }}
    • - {%- endfor %} -
- {%- endif -%} - {%- endblock -%} + - {%- block content -%} - - {%- endblock -%} +
+ {%- block content -%} + + {%- endblock -%} +