diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml new file mode 100644 index 0000000..71ec36f --- /dev/null +++ b/.github/workflows/site.yml @@ -0,0 +1,59 @@ +name: Generate HTML Site from a Drawio diagram with Nasdanika CLI + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up JDK 17 + uses: actions/setup-java@v4 + with: + java-version: '17' + distribution: 'temurin' + - name: Download Nasdanika CLI + run: wget https://github.com/Nasdanika/cli/releases/download/maven-2024.8.0/nsd-cli-2024.8.0.zip + - name: Unzip Nasdanika CLI + run: unzip nsd-cli-2024.8.0.zip + - name: Setup Graphviz + uses: ts-graphviz/setup-graphviz@v2 + - name: Generate site + working-directory: nsd-cli + run: | + chmod u+x nsd + ./nsd drawio ../diagram.drawio html-app -r ../root-action.yml --add-to-root site -r=-1 -F ../page-template.yml ../docs + ls ../docs + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + # Upload entire repository + path: 'docs' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + +# Uncomment to defaults: +# - name: Setup upterm session +# uses: lhotari/action-upterm@v1 +# if: ${{ failure() }} +# with: +# ## If no one connects after 5 minutes, shut down server. +# wait-timeout-minutes: 5 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5ba5c27 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/.$diagram.drawio.bkp diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e48e096 --- /dev/null +++ b/LICENSE @@ -0,0 +1,277 @@ +Eclipse Public License - v 2.0 + + THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE + PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION + OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + +1. DEFINITIONS + +"Contribution" means: + + a) in the case of the initial Contributor, the initial content + Distributed under this Agreement, and + + b) in the case of each subsequent Contributor: + i) changes to the Program, and + ii) additions to the Program; + where such changes and/or additions to the Program originate from + and are Distributed by that particular Contributor. A Contribution + "originates" from a Contributor if it was added to the Program by + such Contributor itself or anyone acting on such Contributor's behalf. + Contributions do not include changes or additions to the Program that + are not Modified Works. + +"Contributor" means any person or entity that Distributes the Program. + +"Licensed Patents" mean patent claims licensable by a Contributor which +are necessarily infringed by the use or sale of its Contribution alone +or when combined with the Program. + +"Program" means the Contributions Distributed in accordance with this +Agreement. + +"Recipient" means anyone who receives the Program under this Agreement +or any Secondary License (as applicable), including Contributors. + +"Derivative Works" shall mean any work, whether in Source Code or other +form, that is based on (or derived from) the Program and for which the +editorial revisions, annotations, elaborations, or other modifications +represent, as a whole, an original work of authorship. + +"Modified Works" shall mean any work in Source Code or other form that +results from an addition to, deletion from, or modification of the +contents of the Program, including, for purposes of clarity any new file +in Source Code form that contains any contents of the Program. Modified +Works shall not include works that contain only declarations, +interfaces, types, classes, structures, or files of the Program solely +in each case in order to link to, bind by name, or subclass the Program +or Modified Works thereof. + +"Distribute" means the acts of a) distributing or b) making available +in any manner that enables the transfer of a copy. + +"Source Code" means the form of a Program preferred for making +modifications, including but not limited to software source code, +documentation source, and configuration files. + +"Secondary License" means either the GNU General Public License, +Version 2.0, or any later versions of that license, including any +exceptions or additional permissions as identified by the initial +Contributor. + +2. GRANT OF RIGHTS + + a) Subject to the terms of this Agreement, each Contributor hereby + grants Recipient a non-exclusive, worldwide, royalty-free copyright + license to reproduce, prepare Derivative Works of, publicly display, + publicly perform, Distribute and sublicense the Contribution of such + Contributor, if any, and such Derivative Works. + + b) Subject to the terms of this Agreement, each Contributor hereby + grants Recipient a non-exclusive, worldwide, royalty-free patent + license under Licensed Patents to make, use, sell, offer to sell, + import and otherwise transfer the Contribution of such Contributor, + if any, in Source Code or other form. This patent license shall + apply to the combination of the Contribution and the Program if, at + the time the Contribution is added by the Contributor, such addition + of the Contribution causes such combination to be covered by the + Licensed Patents. The patent license shall not apply to any other + combinations which include the Contribution. No hardware per se is + licensed hereunder. + + c) Recipient understands that although each Contributor grants the + licenses to its Contributions set forth herein, no assurances are + provided by any Contributor that the Program does not infringe the + patent or other intellectual property rights of any other entity. + Each Contributor disclaims any liability to Recipient for claims + brought by any other entity based on infringement of intellectual + property rights or otherwise. As a condition to exercising the + rights and licenses granted hereunder, each Recipient hereby + assumes sole responsibility to secure any other intellectual + property rights needed, if any. For example, if a third party + patent license is required to allow Recipient to Distribute the + Program, it is Recipient's responsibility to acquire that license + before distributing the Program. + + d) Each Contributor represents that to its knowledge it has + sufficient copyright rights in its Contribution, if any, to grant + the copyright license set forth in this Agreement. + + e) Notwithstanding the terms of any Secondary License, no + Contributor makes additional grants to any Recipient (other than + those set forth in this Agreement) as a result of such Recipient's + receipt of the Program under the terms of a Secondary License + (if permitted under the terms of Section 3). + +3. REQUIREMENTS + +3.1 If a Contributor Distributes the Program in any form, then: + + a) the Program must also be made available as Source Code, in + accordance with section 3.2, and the Contributor must accompany + the Program with a statement that the Source Code for the Program + is available under this Agreement, and informs Recipients how to + obtain it in a reasonable manner on or through a medium customarily + used for software exchange; and + + b) the Contributor may Distribute the Program under a license + different than this Agreement, provided that such license: + i) effectively disclaims on behalf of all other Contributors all + warranties and conditions, express and implied, including + warranties or conditions of title and non-infringement, and + implied warranties or conditions of merchantability and fitness + for a particular purpose; + + ii) effectively excludes on behalf of all other Contributors all + liability for damages, including direct, indirect, special, + incidental and consequential damages, such as lost profits; + + iii) does not attempt to limit or alter the recipients' rights + in the Source Code under section 3.2; and + + iv) requires any subsequent distribution of the Program by any + party to be under a license that satisfies the requirements + of this section 3. + +3.2 When the Program is Distributed as Source Code: + + a) it must be made available under this Agreement, or if the + Program (i) is combined with other material in a separate file or + files made available under a Secondary License, and (ii) the initial + Contributor attached to the Source Code the notice described in + Exhibit A of this Agreement, then the Program may be made available + under the terms of such Secondary Licenses, and + + b) a copy of this Agreement must be included with each copy of + the Program. + +3.3 Contributors may not remove or alter any copyright, patent, +trademark, attribution notices, disclaimers of warranty, or limitations +of liability ("notices") contained within the Program from any copy of +the Program which they Distribute, provided that Contributors may add +their own appropriate notices. + +4. COMMERCIAL DISTRIBUTION + +Commercial distributors of software may accept certain responsibilities +with respect to end users, business partners and the like. While this +license is intended to facilitate the commercial use of the Program, +the Contributor who includes the Program in a commercial product +offering should do so in a manner which does not create potential +liability for other Contributors. Therefore, if a Contributor includes +the Program in a commercial product offering, such Contributor +("Commercial Contributor") hereby agrees to defend and indemnify every +other Contributor ("Indemnified Contributor") against any losses, +damages and costs (collectively "Losses") arising from claims, lawsuits +and other legal actions brought by a third party against the Indemnified +Contributor to the extent caused by the acts or omissions of such +Commercial Contributor in connection with its distribution of the Program +in a commercial product offering. The obligations in this section do not +apply to any claims or Losses relating to any actual or alleged +intellectual property infringement. In order to qualify, an Indemnified +Contributor must: a) promptly notify the Commercial Contributor in +writing of such claim, and b) allow the Commercial Contributor to control, +and cooperate with the Commercial Contributor in, the defense and any +related settlement negotiations. The Indemnified Contributor may +participate in any such claim at its own expense. + +For example, a Contributor might include the Program in a commercial +product offering, Product X. That Contributor is then a Commercial +Contributor. If that Commercial Contributor then makes performance +claims, or offers warranties related to Product X, those performance +claims and warranties are such Commercial Contributor's responsibility +alone. Under this section, the Commercial Contributor would have to +defend claims against the other Contributors related to those performance +claims and warranties, and if a court requires any other Contributor to +pay any damages as a result, the Commercial Contributor must pay +those damages. + +5. NO WARRANTY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT +PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS" +BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR +IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF +TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR +PURPOSE. Each Recipient is solely responsible for determining the +appropriateness of using and distributing the Program and assumes all +risks associated with its exercise of rights under this Agreement, +including but not limited to the risks and costs of program errors, +compliance with applicable laws, damage to or loss of data, programs +or equipment, and unavailability or interruption of operations. + +6. DISCLAIMER OF LIABILITY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT +PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS +SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST +PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE +EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + +7. GENERAL + +If any provision of this Agreement is invalid or unenforceable under +applicable law, it shall not affect the validity or enforceability of +the remainder of the terms of this Agreement, and without further +action by the parties hereto, such provision shall be reformed to the +minimum extent necessary to make such provision valid and enforceable. + +If Recipient institutes patent litigation against any entity +(including a cross-claim or counterclaim in a lawsuit) alleging that the +Program itself (excluding combinations of the Program with other software +or hardware) infringes such Recipient's patent(s), then such Recipient's +rights granted under Section 2(b) shall terminate as of the date such +litigation is filed. + +All Recipient's rights under this Agreement shall terminate if it +fails to comply with any of the material terms or conditions of this +Agreement and does not cure such failure in a reasonable period of +time after becoming aware of such noncompliance. If all Recipient's +rights under this Agreement terminate, Recipient agrees to cease use +and distribution of the Program as soon as reasonably practicable. +However, Recipient's obligations under this Agreement and any licenses +granted by Recipient relating to the Program shall continue and survive. + +Everyone is permitted to copy and distribute copies of this Agreement, +but in order to avoid inconsistency the Agreement is copyrighted and +may only be modified in the following manner. The Agreement Steward +reserves the right to publish new versions (including revisions) of +this Agreement from time to time. No one other than the Agreement +Steward has the right to modify this Agreement. The Eclipse Foundation +is the initial Agreement Steward. The Eclipse Foundation may assign the +responsibility to serve as the Agreement Steward to a suitable separate +entity. Each new version of the Agreement will be given a distinguishing +version number. The Program (including Contributions) may always be +Distributed subject to the version of the Agreement under which it was +received. In addition, after a new version of the Agreement is published, +Contributor may elect to Distribute the Program (including its +Contributions) under the new version. + +Except as expressly stated in Sections 2(a) and 2(b) above, Recipient +receives no rights or licenses to the intellectual property of any +Contributor under this Agreement, whether expressly, by implication, +estoppel or otherwise. All rights in the Program not expressly granted +under this Agreement are reserved. Nothing in this Agreement is intended +to be enforceable by any entity that is not a Contributor or Recipient. +No third-party beneficiary rights are created under this Agreement. + +Exhibit A - Form of Secondary Licenses Notice + +"This Source Code may also be made available under the following +Secondary Licenses when the conditions for such availability set forth +in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), +version(s), and exceptions or additional permissions here}." + + Simply including a copy of this Agreement, including this Exhibit A + is not sufficient to license the Source Code under Secondary Licenses. + + If it is not possible or desirable to put the notice in a particular + file, then You may include the notice in a location (such as a LICENSE + file in a relevant directory) where a recipient would be likely to + look for such a notice. + + You may add additional accurate notices of copyright ownership. diff --git a/README.md b/README.md new file mode 100644 index 0000000..0326392 --- /dev/null +++ b/README.md @@ -0,0 +1,461 @@ +# Drawio Site + +This is a template repository for web sites generated from [Drawio](https://www.drawio.com/) diagrams with [GitHub Actions](https://docs.github.com/en/actions) and [Nasdanika CLI Drawio Command](https://docs.nasdanika.org/nsd-cli/nsd/drawio/index.html). + + +## Demos + +Below is a list of sites created from this template: + +...TODO... + +## Quick start video + +
+ +
+ +## Steps + +* On the [repository page](https://github.com/Nasdanika-Templates/drawio-site) click "Use this template" button in the top right. +* Once you create a new repository, go to the Settings > Pages and select "GitHub Actions" as source. +* Click on the Acitons tab. You should see a failed deployment. Manually trigger ``Generate HTML Site from a Drawio diagram with Nasdanika CLI`` action. Once it is successful, open the pages site. +* Customize the diagram, root action, and page template to your needs as explained below. + +The deployment action can be triggered manually from the actions page. +It can be useful if your site references external resources. + +For example: + +* The diagram file may link to pages in external diagrams (federated diagrams) +* The diagram file may reference external documentation resources + +## Deployment process + +* [Nasdanika CLI](https://docs.nasdanika.org/nsd-cli/index.html) is downloaded and extracted +* ``[drawio](https://docs.nasdanika.org/nsd-cli/nsd/drawio/index.html) [html-app](https://docs.nasdanika.org/nsd-cli/nsd/drawio/html-app/index.html) ... [site](https://docs.nasdanika.org/nsd-cli/nsd/drawio/html-app/site/index.html) ...`` command pipeline is executed to generate a Web site +* The generated site is deployed to [GitHub Pages](https://pages.github.com/). + +## Diagram file + +You may rename ``diagram.drawio`` to something more meaningful, e.g.``my-system.drawio``. +Or you may use a pre-existing drawio diagram and delete ``diagram.drawio``. +You can also use an external diagram and reference it by URL. +If you do rename/replace the diagram, open ``.github/workflows/site.yml`` and update line 40 with a new diagram file name. + +## Page template + +In the page template file you can: + +* Modify the [theme](https://javadoc.io/doc/org.nasdanika.html/bootstrap/latest/org.nasdanika.html.bootstrap/org/nasdanika/html/bootstrap/Theme.html) on line 3 - choose one of 20+ [Bootswatch themes](https://bootswatch.com/4/) or the default theme. Please note that generated sites look good with light themes, and not so good (in my personal opinion) with dark themes. +* Highly recommended: remove out-of-the-box Google analytics script at lines 23-33 - replace it with your own or remove the header section (lines 22-33) altogether. +* Remove line 36 or set ``fluid`` to ``false``. +* Modify [navigation panel style](https://html-app.models.nasdanika.org/references/eClassifiers/NavigationPanelStyle/index.html) at line 38 + +## Root action + +The root action defines: + +* The header (root action[^action_types]). You may modify the icon and the title. +* Root navigation actions - lines 6 - 20. Glossary and search are functional, but not perfect - they need TLC, which I don't have capacity for at the moment. You may use them AS-IS, remove/replace, or improve and create a pull request. +* Footer (root navigation) at lines 21+. Out of the box is links to the template repository site - update or remove. + +[^action_types]: See [Action types](https://html-app.models.nasdanika.org/index.html#action-types) + +## Diagram elements + +You can add documentation to diagram elements, ``title`` and ``icon`` property, customize element ID, and link elements to pages or other elements, including pages and elements in other diagram files. + +Site pages are generated only for elements with documentation. + +Important: Pages are not generated for diagram elements without labels or ``title`` property! It may lead to broken links. + +### Documentation + +You can add inline documentation in ``documentation`` property as it is done for [Alice](https://nasdanika-templates.github.io/drawio-site/alice/index.html). + +Documentation is by default treated as Markdown. +Use ``doc-format`` property to specify documentation format. +Out of the box there are 3 formats supported: + +* ``markdown`` +* ``html`` +* ``text`` + +You can add support for more formats, e.g. [Asciidoc](https://docs.asciidoctor.org/asciidoc/latest/) using [AsciidoctorJ](https://github.com/asciidoctor/asciidoctorj) - see "Adding support for documentation format" below. + +You may reference an external documentation resources with ``doc-ref`` property - this how it is done for the diagram root (click on the diagram canvas and then on "Edit Data" button in the right panel). +Documentation reference is a URL resolved relative to the diagram file location. + +If you use ``doc-ref`` property, the documentation format is inferred from the extension. +You may override the inferred value using ``doc-format`` property. + +### Title + +By default the element label is used as action text. +For elements with long labels it may be desirable to use shorter text. +To do so use ``title`` property. + +### Icon + +By default element icons are derived from element images where possible. +Otherwise a default icon is used. +You may use ``icon`` property to customize element icon. +The icon can be a URL (including data URL) or a CSS style e.g. ``fas fa-user``. + +### ID + +Element ID's are used to construct element page URL's. +Element ID's are generated as long random strings. +They are editable - double-click on the ID at the top of the data dialog. +So, if you'd like to have semantic URL's - customize the ID's. + +## Page and element links + +You may link elements to pages and other element using the [extended link syntax](https://docs.nasdanika.org/core/drawio/index.html#page-and-element-links). + +When an element links to a page, the page root[^api] is logically merged with the linking element and page elements (except elements liking to other elements) become logical children of the linking element. + +If an element links to another element, then that element is not considered a logical child of the page/root/page linking element. +The link chain is traversed and the diagram element on the generated site is linked to the page of the link target element if that element has a page (i.e. it is documented). Otherwise there is no link. + +[^api]: See [Drawio API](https://docs.nasdanika.org/core/drawio/index.html#api) + +## Multiple top-level pages + +A top-level diagram page is a page that is not linked from any diagram element. +If there is more than one top-level page, then you may want to add a principal action to the ``root-action.yml`` and link pages to the principal action by removing ``--add-to-root`` option from the command line. + +See TODO for an example. + +## Markdown + +This section demonstrates advanced capabilities of Markdown documentation. + +### Embedded images + +You can embed PNG and JPEG using fenced blocks. + +#### PNG resource + + ```png-resource + isa.png + ``` + +Resource location is resolved relative to the diagram file location. + +#### JPEG resource + + ```jpeg-resource + my.jpeg + ``` + +#### PNG + + ```png + Base 64 encoded png + ``` +#### JPEG + + ```jpeg + Base 64 encoded jpeg + ``` + +### Embedded diagrams + +You can also embed [PlantUML](https://plantuml.com/), Drawio, and [Mermaid](https://mermaid-js.github.io/mermaid/#/) diagrams using fenced blocks. + +#### Drawio + + ```drawio-resource + aws.drawio + ``` + +Resource location is resolved in the same way as for image files as explained above. + +#### PlantUML + +PlantUML diagrams can be defined inline or loaded from resources. + +##### Loading from a resource + + ```uml-resource + sequence.plantuml + ``` + +##### Inline + +The following language specifications (dialects) are supported: + +* ``uml`` - for the following diagram types: + * [Sequence](https://plantuml.com/sequence-diagram), + * [Use Case](https://plantuml.com/use-case-diagram), + * [Class](https://plantuml.com/class-diagram), + * [Activity](https://plantuml.com/activity-diagram-beta), + * [Component](https://plantuml.com/component-diagram), + * [State](https://plantuml.com/state-diagram), + * [Object](https://plantuml.com/object-diagram), + * [Deployment](https://plantuml.com/deployment-diagram), + * [Timing](https://plantuml.com/timing-diagram), + * [Network](https://plantuml.com/nwdiag). +* ``wireframe`` - for [Wireframe diagrams](https://plantuml.com/salt) +* ``gantt`` - for [Gantt diagrams](https://plantuml.com/gantt-diagram) +* ``mindmap`` - for [Mind Maps](https://plantuml.com/mindmap-diagram) +* ``wbs`` - for [Work Breakdown Structures](https://plantuml.com/wbs-diagram) + +###### UML + +**Sequence** + +Fenced block: + + ```uml + Alice -> Bob: Authentication Request + Bob --> Alice: Authentication Response + ``` + +Diagram: + +```uml +Alice -> Bob: Authentication Request +Bob --> Alice: Authentication Response +``` + +**Component** + +Component diagram with links to component pages. + + +Fenced block: + + ```uml + package Core { + component Common [[https://github.com/Nasdanika/core/tree/master/common]] + } + + package HTML { + component HTML as html [[https://github.com/Nasdanika/html/tree/master/html]] + [html] ..> [Common] + } + ``` + +Diagram: + +```uml +package Core { + component Common [[https://github.com/Nasdanika/core/tree/master/common]] +} + +package HTML { + component HTML as html [[https://github.com/Nasdanika/html/tree/master/html]] + [html] ..> [Common] +} +``` + +**Wireframe** + +Fenced block: + + ```wireframe + { + Just plain text + [This is my button] + () Unchecked radio + (X) Checked radio + [] Unchecked box + [X] Checked box + "Enter text here " + ^This is a droplist^ + } + ``` + + +Diagram: + +```wireframe +{ + Just plain text + [This is my button] + () Unchecked radio + (X) Checked radio + [] Unchecked box + [X] Checked box + "Enter text here " + ^This is a droplist^ +} +``` + +**Gantt** + +Fenced block: + + ```gantt + [Prototype design] lasts 15 days and links to [[https://docs.nasdanika.org/index.html]] + [Test prototype] lasts 10 days + -- All example -- + [Task 1 (1 day)] lasts 1 day + [T2 (5 days)] lasts 5 days + [T3 (1 week)] lasts 1 week + [T4 (1 week and 4 days)] lasts 1 week and 4 days + [T5 (2 weeks)] lasts 2 weeks + ``` + +Diagram: + +```gantt +[Prototype design] lasts 15 days and links to [[https://docs.nasdanika.org/index.html]] +[Test prototype] lasts 10 days +-- All example -- +[Task 1 (1 day)] lasts 1 day +[T2 (5 days)] lasts 5 days +[T3 (1 week)] lasts 1 week +[T4 (1 week and 4 days)] lasts 1 week and 4 days +[T5 (2 weeks)] lasts 2 weeks +``` + +**Mind Map** + +Fenced block: + + ```mindmap + * Debian + ** [[https://ubuntu.com/ Ubuntu]] + *** Linux Mint + *** Kubuntu + *** Lubuntu + *** KDE Neon + ** LMDE + ** SolydXK + ** SteamOS + ** Raspbian with a very long name + *** Raspmbc => OSMC + *** Raspyfi => Volumio + ``` + +Diagram: + +```mindmap +* Debian +** [[https://ubuntu.com/ Ubuntu]] +*** Linux Mint +*** Kubuntu +*** Lubuntu +*** KDE Neon +** LMDE +** SolydXK +** SteamOS +** Raspbian with a very long name +*** Raspmbc => OSMC +*** Raspyfi => Volumio +``` + +**WBS** + +WBS elements can have links. This type of diagram can also be used to display organization structure. + + ```wbs + * [[https://docs.nasdanika.org/index.html Business Process Modelling WBS]] + ** Launch the project + *** Complete Stakeholder Research + *** Initial Implementation Plan + ** Design phase + *** Model of AsIs Processes Completed + **** Model of AsIs Processes Completed1 + **** Model of AsIs Processes Completed2 + *** Measure AsIs performance metrics + *** Identify Quick Wins + ** Complete innovate phase + ``` + +Fenced block: + + +Diagram: + +```wbs +* [[https://docs.nasdanika.org/index.html Business Process Modelling WBS]] +** Launch the project +*** Complete Stakeholder Research +*** Initial Implementation Plan +** Design phase +*** Model of AsIs Processes Completed +**** Model of AsIs Processes Completed1 +**** Model of AsIs Processes Completed2 +*** Measure AsIs performance metrics +*** Identify Quick Wins +** Complete innovate phase +``` + +#### Mermaid + +You can define [Mermaid](https://mermaid-js.github.io/mermaid/#/) diagrams in ``mermaid`` fenced blocks: + + ```mermaid + flowchart LR + Alice --> Bob & Chuck --> Deb + ``` + +results in this diagram: + +```mermaid +flowchart LR + Alice --> Bob & Chuck --> Deb +``` + +##### Loading from a resource + +It is also possible to load a diagram definition from a resource resolved relative to the model resource: + + ```mermaid-resource + sequence.mermaid + ``` + +### Extensions + +* [Table of contents](https://github.com/vsch/flexmark-java/wiki/Table-of-Contents-Extension) - add ``[TOC]`` to the document as explained in the documentation. This extension will create a table of contents from markdown headers. +* [Footnotes](https://github.com/vsch/flexmark-java/wiki/Footnotes-Extension) +* Strikethrough: ``~~strikethrough~~``-> ~~strikethrough~~ +* Subscript: ``H~2~O`` -> H~2~0 +* Superscript: ``2^5^ = 32`` -> 2^5^ = 32 + +## Failing on errors + +``-r=-1`` command line option means "don't fail on page errors" such as: + +* Blank pages +* Broken internal links +* Missing resources + +Missing resources are reported on pages using danger alert blocks. + +If you want to prevent deployment of a site with page errors, remove the option or set it to the expected number of errors - there might be "known errors" which you are OK to live with. + +## Upgrading NSD CLI version + +When a new version of Nasdanika CLI is released you may update lines 33 and 35 in ``site.yml`` to point to the new distribution. + +## Adding support for a new documentation format + +To add a new documentation format: + +* Create a Maven module +* Create a documentation [capability](https://docs.nasdanika.org/core/capability/index.html) factory class, see [MarkdownDocumentationFactory](https://github.com/Nasdanika/core/blob/master/exec/src/main/java/org/nasdanika/exec/util/MarkdownDocumentationFactory.java) +* Register it in ``module-info.java`` - [example](https://github.com/Nasdanika/core/blob/master/exec/src/main/java/module-info.java) +* Build a custom CLI with the above module as a dependency. See [Demo CLI](https://github.com/Nasdanika-Demos/cli) for an example. +* Build a distribution, deploy to a web location, and update ``site.yml`` lines 33 and 35. + +## Next steps + +This section outlines possible next steps once you have a site generated from a diagram or a set of diagrams. + +### Executable diagrams + +You may make the diagrams executable. TODO - links to demos + +#### Dynamic proxy + +#### HTTP Routes + +### Semantic mapping + +You can also "upgrade" to semantic mapping as explained in the [Beyond Diagrams](https://leanpub.com/beyond-diagrams) book and TODO story. diff --git a/diagram.drawio b/diagram.drawio new file mode 100644 index 0000000..1ab267c --- /dev/null +++ b/diagram.drawio @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/page-template.yml b/page-template.yml new file mode 100644 index 0000000..45f4d03 --- /dev/null +++ b/page-template.yml @@ -0,0 +1,41 @@ +bootstrap.Page: + cdn: true + theme: Cerulean + name: Application Page Template + language: EN + stylesheets: + - https://cdn.jsdelivr.net/gh/Nasdanika/html@master/model/app.gen/web-resources/css/app.css + - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.1/css/all.min.css + - https://cdn.jsdelivr.net/npm/jstree@3.3.11/dist/themes/default/style.min.css + - https://cdn.jsdelivr.net/npm/github-markdown-css@5.1.0/github-markdown.min.css + - https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.3.1/build/styles/default.min.css + - https://cdn.jsdelivr.net/npm/bootstrap-vue@2.21.2/dist/bootstrap-vue.css + scripts: + - https://cdn.jsdelivr.net/gh/Nasdanika/html@master/model/app.gen/web-resources/js/common.js + - https://cdn.jsdelivr.net/gh/Nasdanika/html@master/model/app.gen/web-resources/js/dark-head.js + - https://cdn.jsdelivr.net/npm/jstree@3.3.11/dist/jstree.min.js + - https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.3.1/build/highlight.min.js + - https://cdn.jsdelivr.net/npm/vue@2.6.14/dist/vue.min.js + - https://cdn.jsdelivr.net/npm/bootstrap-vue@2.21.2/dist/bootstrap-vue.min.js + - https://cdn.jsdelivr.net/gh/Nasdanika/html@master/model/app.gen/web-resources/js/components/table.js + - https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js + head: + # Google analytics + content.Text: |+2 + + + + body: + app.Page: + fluid: true + navigation-panel: + style: SEARCHABLE_TREE # COLLAPSIBLE_CARDS + collapsible: true + + diff --git a/root-action.yml b/root-action.yml new file mode 100644 index 0000000..8c47af6 --- /dev/null +++ b/root-action.yml @@ -0,0 +1,25 @@ +Action: + icon: https://docs.nasdanika.org/images/nasdanika-logo.png + text: Nasdanika Templates + # location: https://github.com/Nasdanika-Demos - breaks the site in 2024.8.0, will be fixed in subsequent releases + children: + - Action: + location: ${base-uri}search.html + icon: fas fa-search + text: Search + content: + Interpolator: + source: + exec.content.Resource: classpath://org/nasdanika/html/model/app/gen/search.html + - Action: + location: ${base-uri}glossary.html + text: Glossary + content: + Interpolator: + source: + exec.content.Resource: classpath://org/nasdanika/html/model/app/gen/semantic-info.html + navigation: + - Action: + text: Source + icon: fab fa-github + location: https://github.com/Nasdanika-Templates/drawio-site