web-documentation 1.0.23 → 1.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-documentation",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "Declarative multilanguage documentation website generator",
   "keywords": [
     "documentation",
@@ -68,7 +68,7 @@
     "@webcomponents/webcomponentsjs": "^2.8.0",
     "archiver": "^8.0.0",
     "bootstrap-icons": "^1.13.1",
-    "clientnode": "^4.0.1411",
+    "clientnode": "^4.0.1414",
     "css-loader": "^7.1.4",
     "cssnano": "^8.0.1",
     "default-gateway": "^7.2.2",
@@ -204,7 +204,7 @@
         "ejs": {
           "options": {
             "locals": {
-              "API_DOCUMENTATION_PATH": "/apiDocumentation/",
+              "API_DOCUMENTATION_PATH": "/api/",
               "CONTENT": "source/dummyReadme.md",
               "DISTRIBUTION_BUNDLE_FILE_PATH": "dummyDistributionBundle.zip",
               "LANGUAGES": {

package/source/deploy.ts

@@ -497,7 +497,11 @@ const tidyUp = async (): Promise<void> => {
         HAS_API_DOCUMENTATION &&
         !(await isDirectory(oldAPIDocumentationDirectoryPath))
     )
-        run(`git checkout '${oldAPIDocumentationDirectoryPath}'`)
+        try {
+            run(`git checkout '${oldAPIDocumentationDirectoryPath}'`)
+        } catch (error) {
+            log.warn(error)
+        }
 
     if (!run('git branch').includes('* main'))
         log.debug(run('git checkout main'))
@@ -578,8 +582,9 @@ const main = async (): Promise<void> => {
             log.info('API documentation creation script detected.')
             try {
                 log.debug(run('yarn document'))
+                log.info('API documentation created.')
             } catch (error) {
-                log.error(error)
+                log.warn(error)
                 HAS_API_DOCUMENTATION = false
             }
         }
@@ -680,13 +685,19 @@ const main = async (): Promise<void> => {
         log.debug(
             run('corepack install', {cwd: temporaryDocumentationFolderPath})
         )
-        log.debug(run(
-            'yarn install',
-            {
-                cwd: temporaryDocumentationFolderPath,
-                env: {...process.env, NODE_ENV: 'debug'}
-            }
-        ))
+
+        try {
+            log.debug(run(
+                'yarn install',
+                {
+                    cwd: temporaryDocumentationFolderPath,
+                    env: {...process.env, NODE_ENV: 'debug'}
+                }
+            ))
+        } catch (error) {
+            log.warn(error)
+        }
+
         log.debug(run('yarn clear', {cwd: temporaryDocumentationFolderPath}))
 
         await generateAndPushNewDocumentationPage(

package/source/dummyReadme.md

@@ -60,18 +60,16 @@ You need utilities for:<!--deDE:Sie benötigen Hilfsfunktionen für:-->
 - URLs
 
 <!--Place for automatic generated table of contents.-->
-<div class="doc-toc" style="display:none">
+<div class="wd-table-of-contents" style="display: none">
     <!--|deDE:Inhalt-->
     <h2 id="content">Content</h2>
+    <!--wd-table-of-contents-->
 </div>
 
 <!--|deDE:Installation-->
 Installation
 ------------
 
-<!--|deDE:Klassische Dom-Integration-->
-### Classical dom injection
-
 You can install via package manager, simply download the compiled version as
 zip file here and inject or request via cdn in HTML:
 <!--deDE:

package/source/index.ts

@@ -76,7 +76,9 @@ export class WebDocumentation<
             }}"
         >
             <web-internationalization
-                options="{selectors: {knownTranslation: '.doc-toc'}}"
+                options="{selectors: {
+                    knownTranslation: '.wd-table-of-contents'
+                }}"
             >
                 <slot>Please provide a template to transclude.</slot>
             </web-internationalization>
@@ -97,8 +99,8 @@ export class WebDocumentation<
                 '.section__home h1, .section__home h2, ' +
                 '.section__home h3, .section__home h4, ' +
                 '.section__home h5, .section__home h6',
-            tableOfContent: '.doc-toc',
-            tableOfContentLinks: '.doc-toc ul li a[href^="#"]'
+            tableOfContent: '.wd-table-of-contents',
+            tableOfContentLinks: '.wd-table-of-contents ul li a[href^="#"]'
         },
 
         showExample: {
@@ -170,7 +172,7 @@ export class WebDocumentation<
      * @param reason - Why an update has been triggered.
      * @param resolveRendering - Indicates whether rendering should be resolved
      * finally. Should be set to "false" via super calls in inherited render
-     * methods which do further dom manipulations afterwards and resolve the
+     * methods which do further dom manipulations afterward and resolve the
      * rendering process by their own.
      * @returns A promise resolving when rendering has finished. A promise may
      * be needed for classes inheriting from this class.
@@ -237,7 +239,8 @@ export class WebDocumentation<
         if (!this.tableOfContentDomNode)
             return
 
-        let listItems = '<ul>'
+        let listItemsHTML = ''
+
         let level = 0
         let firstLevel = 0
         let first = true
@@ -253,11 +256,11 @@ export class WebDocumentation<
                 firstLevel = newLevel
 
             if (newLevel > level)
-                listItems += '<ul>'
+                listItemsHTML += '<ul>'
             else if (newLevel < level)
-                listItems += '</ul>'
+                listItemsHTML += '</ul>'
 
-            listItems += `
+            listItemsHTML += `
                 <li>
                     <a href="#${domNode.getAttribute('id') ?? 'unknown'}">
                         ${domNode.innerText}
@@ -270,13 +273,18 @@ export class WebDocumentation<
         }
         // Close remaining inner lists.
         while (level < firstLevel) {
-            listItems += '</ul>'
+            listItemsHTML += '</ul>'
             level += 1
         }
 
-        listItems += '</ul>'
-
-        this.tableOfContentDomNode.append(createDomNodes(listItems))
+        for (const domNode of this.tableOfContentDomNode.childNodes)
+            if (
+                domNode.nodeType === Node.COMMENT_NODE &&
+                domNode.nodeValue === 'wd-table-of-contents'
+            ) {
+                domNode.after(createDomNodes(listItemsHTML))
+                domNode.remove()
+            }
 
         this.tableOfContentLinkDomNodes =
             this.tableOfContentDomNode.querySelectorAll<HTMLAnchorElement>(
@@ -301,7 +309,8 @@ export class WebDocumentation<
                 }
             )
 
-        this.tableOfContentDomNode.style.display = 'initial'
+        if (this.tableOfContentDomNode.style.display === 'none')
+            this.tableOfContentDomNode.style.display = 'initial'
     }
     /**
      * This method makes dotes after code lines which are too long. This

package/source/renderMarkdown.mjs

@@ -6,6 +6,8 @@ import {markedXhtml} from 'marked-xhtml'
 
 const {getLanguage, highlight} = highlightJSModule
 
+const TOC_INDICATOR_HTML = '<!--wd-table-of-contents-->'
+
 const marked = new Marked(
     markedHighlight({
         /*
@@ -22,8 +24,29 @@ const marked = new Marked(
 
 export default (options) => {
     marked.setOptions(options)
-    // Include an id attribute when emitting headings (h1, h2, h3, etc).
-    marked.use(gfmHeadingId({prefix: 'doc-'}))
+    // Include an id attribute when emitting headings (h1, h2, h3, ...).
+    marked.use(gfmHeadingId(
+        {prefix: 'wd-heading-'},
+        {
+            hooks: {
+                // Adds an autogenerated table of contents list.
+                postprocess: (html) => {
+                    const headings = getHeadingList()
+                    const tableOfContents = `
+                        <ul>${
+                            headings
+                                .map(({id, raw, level}) =>
+                                    `<li><a href="#${id}">${raw}</a></li>`
+                                )
+                                .join('\n')
+                        }</ul>
+                    `
+
+                    return html.replace(TOC_INDICATOR_HTML, tableOfContents)
+                }
+            }
+        }
+    ))
     // Favors self-closing xhtml tags.
     marked.use(markedXhtml())