diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md new file mode 100644 index 0000000000000000000000000000000000000000..7ac87e36910b2eaa5cf664aca14311c2d3dd3227 --- /dev/null +++ b/.gitlab/issue_templates/bug.md @@ -0,0 +1,26 @@ +# Error report template + +## Title of the error +Short, precise description of the error. + +## Location of the error +Describe where the error occurred. Is it an error in the application, the documentation, or elsewhere? + +## Description of the error +A detailed description of the error and how you came across it. Is the error reproducible? If yes, how? + +## Screenshot(s) +Include screenshots that visualise the error. This is particularly useful for layout issues or if the context is important for understanding the error. + +## Effects of the error +Describe the impact of the error on the user experience or functionality of the project. + +## Suggestions for correction +If you have any suggestions on how to fix the bug, please share them here. + +## Additional information / comments +Here you can add any additional information or specific comments that may be relevant to identifying or correcting the bug. + +--- + +Your accurate and precise description of the error will help us to continuously improve the quality of this project. Thank you for your contribution! diff --git a/.gitlab/issue_templates/feature.md b/.gitlab/issue_templates/feature.md new file mode 100644 index 0000000000000000000000000000000000000000..daf9ffd440f71ca6aed1fe2dc00cbe427593dd19 --- /dev/null +++ b/.gitlab/issue_templates/feature.md @@ -0,0 +1,23 @@ +# Feature Template + +## Title of the request +Short, precise description of the desired further development or customisation. + +## Detailed description +A detailed description of what is to be changed or added. Please explain the purpose and expected benefit of this request. + +## Justification of the request +Explain why this enhancement or customisation is important for the project. This could be an improvement to the user experience or functionality. + +## Proposed implementation (optional) +If you have suggestions or ideas on how this request could be implemented, please describe them here. This can include designs, technical details or examples of similar implementations. + +## Possible impact +Describe what impact this change could have on the overall project or its users. This includes both positive and possible negative consequences. + +## Additional information / notes +Add any additional information here that may be relevant to understanding or evaluating your request. + +--- + +Your detailed and well-reasoned enquiry is very helpful to us. Thank you for your contribution and ideas! diff --git a/.gitlab/issue_templates/security_advisory.md b/.gitlab/issue_templates/security_advisory.md new file mode 100644 index 0000000000000000000000000000000000000000..83e4cede591ab65880b3cb9d491383a68eac5c02 --- /dev/null +++ b/.gitlab/issue_templates/security_advisory.md @@ -0,0 +1,22 @@ +# Security advisory + +If known, please provide the following information if applicable: + +- Common Vulnerabilities and Exposures (CVE) identifier: +- Common weakness enumerator (CWE): + +## Impact + +What type of vulnerability is this? Who is affected? + +## Patches + +Has the issue been patched? Which versions should users update to? + +## Workarounds + +Is there a way for users to fix the vulnerability without upgrading? + +## References + +Are there links that users can visit to learn more? diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000000000000000000000000000000000000..ec8ed8dc78dab7fd0695d3446fe013e007827e08 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,17 @@ +# Changelog + +All significant changes to this project are documented in this file. + +## [Unreleased] + +## [0.2.5] - 2025-02-19 + +_Tracking Starting Point_ + +## General notes + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +[Unreleased]: https://gitlab.opencode.de/open-code/document-writing-tools/document-writing-ci-components/-/compare/0.2.5...HEAD +[0.2.5]: https://gitlab.opencode.de/open-code/document-writing-tools/document-writing-ci-components/-/commits/0.2.5 \ No newline at end of file diff --git a/CLA/CLA_de.pdf b/CLA/CLA_de.pdf new file mode 100644 index 0000000000000000000000000000000000000000..8374af67aede9dab4b4b4e9203cc7a580371e58e Binary files /dev/null and b/CLA/CLA_de.pdf differ diff --git a/CLA/CLA_en.pdf b/CLA/CLA_en.pdf new file mode 100644 index 0000000000000000000000000000000000000000..2372e20343cb0f79a54040e90bee7a1cfa0467d2 Binary files /dev/null and b/CLA/CLA_en.pdf differ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index acde7b7ebffffe3c22d0f89b85a75c18abc071fc..6535171f9a7f8511e97c5f09c5f67268ffc4244a 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,147 +1,133 @@ -## 1. Zielsetzung -Der Code of Conduct unterstützt unser Bestreben, gutes Verhalten zu fördern und schlechtes Verhalten in unserer Gemeinschaft zu unterbinden. +# Contributor Covenant Code of Conduct -Ziel des Code of Conduct für die Architekturrichtlinie des Bundes ist es, das größtmögliche Spektrum an Menschen mit den unterschiedlichsten und vielfältigsten Hintergründen zu integrieren und den Austausch zwischen ihnen zu fördern. Wir sehen uns verpflichtet, eine freundliche, sichere und einladende Umgebung zu schaffen, unabhängig von Geschlecht und geschlechtlicher Identität, sexueller Orientierung, körperlichen und geistigen Fähigkeiten, ethnischer Herkunft und Nationalität, Religion und Weltanschauung, Alter und sozialer Herkunft sowie gesellschaftlichem und wirtschaftlichem Status. +## Our Pledge -Dieser Code of Conduct skizziert unsere Erwartungen an alle, die an unserer Gemeinschaft teilnehmen, sowie Schritte zur Meldung inakzeptablen Verhaltens. Wir laden alle ein, uns dabei zu unterstützen, sichere und positive Erfahrungen für alle zu schaffen. +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. -## 2. Geltungsbereich +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. -Wir erwarten von allen Mitwirkenden, dass sie sich bei jeder Interaktion mit dieser Gemeinschaft – online oder persönlicher Natur - an diesen Code of Conduct halten. +## Our Standards -Hierbei stellt dieser Code of Conduct nicht abschließend alle Regeln für eine freundliche, sichere und inklusive Interaktion in der Gemeinschaft auf, sondern transportiert unsere Wertvorstellungen und versteht sich als Richtschnur, Hinweisgeber und Inspiration für ein für alle positives und werthaltiges Miteinander. +Examples of behavior that contributes to a positive environment for our +community include: -## 3. Bekenntnis zur Vielfalt +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community -Wir ermutigen alle Personen unter Einhaltung dieses Code of Conduct, unterschiedliche Perspektiven in das Projekt einzubringen. +Examples of unacceptable behavior include: -## 4. Unsere Grundsätze +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting -Gemeinsam streben wir mit unserem Verhalten danach, zur Schaffung einer positiven Umgebung beizutragen. Da die primäre Art der Kommunikation in Textform erfolgt und es somit an dem häufig für das Verständnis entscheidenden Tonfall, Gestik oder anderen Kontext mangelt, ist es besonders wichtig, dass diese positiven Verhaltensweisen auch in der schriftlichen Kommunikation vermittelt wird. +## Enforcement Responsibilities -Die folgenden Verhaltensweisen werden von allen Teilnehmenden erwartet und eingefordert: +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. -Nehmen Sie Rücksicht aufeinander und gehen Sie respektvoll miteinander um. -Verwenden Sie eine einladende und inklusive Sprache und wählen Sie Worte sorgsam aus. -Gehen Sie von positiven Intentionen Ihres Gegenübers aus. -Seien Sie geduldig und respektieren Sie die Zeit und Aufmerksamkeit der Gemeinschaft. -Konzentrieren Sie sich auf das, was für die Gemeinschaft am besten ist. -Fördern Sie aktiv den Austausch und die Zusammenarbeit in der Gemeinschaft. -Üben Sie konstruktive Kritik und nehmen Sie solche mit Anstand an. +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. -## 5. Inakzeptable Verhaltensweisen +## Scope -Wir akzeptieren keine Verhaltensweisen, die gegen unseren Code of Conduct verstoßen, und sind achtsam gegenüber unserer Umgebung und allen Teilnehmenden. +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. -Fehlverhalten oder Verstöße gegen diesen Code of Conduct sind bitte zu melden, auch wenn sie unbedeutend erscheinen. +## Enforcement -Die folgenden Verhaltensweisen werden als inakzeptabel angesehen und werden in unserer Gemeinschaft nicht toleriert: +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[info@opencode.de](mailto:info@opencode.de). +All complaints will be reviewed and investigated promptly and fairly. -Sexistische, rassistische, homophobe, transphobe oder anderweitig diskriminierende Anspielungen, Äußerungen und Sprachwahl. -Persönliche Beleidigungen, insbesondere solche, die sich auf Geschlecht, sexuelle Orientierung, Herkunft, Religion, Lebensgewohnheiten oder Behinderung beziehen. -Einschüchterung, Gewalt, Gewaltandrohung oder gewalttätige Sprache, die gegen eine andere Person gerichtet ist. -Unerwünschte sexuelle Aufdringlichkeit in Sprache und Handeln. -Das Veröffentlichen oder Anzeigen von sexuellem oder gewalttätigem Material. -Anhaltende Störung der Diskussion. -Befürwortung oder Ermutigung zu einer der oben genannten Verhaltensweisen. -Wir können weder alle Formen von inakzeptablem Verhalten und Belästigung vollständig auflisten, noch versuchen wir, einige Formen davon als harmlos oder nicht aktionswürdig zu deklarieren. Vielmehr bitten wir, den Vorfall zu melden, wenn Sie sich belästigt fühlen. Die Meldung wird diskret behandelt und es werden Lösungswege gesucht, ohne dies öffentlich im Forum anzusprechen, da dies tendenziell die Probleme für Betroffene und die Gemeinschaft im Ganzen eher verschärft. +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. -## 6. Aktiv werden bei Verstößen +## Enforcement Guidelines -Bitte werden Sie aktiv und melden jeden Verstoß gegen den Code of Conduct. +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: -Wenn Sie von inakzeptablem Verhalten betroffen sind, davon Zeuge werden oder andere Bedenken haben, benachrichtigen Sie bitte direkt: +### 1. Correction -DGII3AG@bmi.bund.de +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. -Wir bitten darum, dass Ihr Bericht Folgendes enthält: +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. -Ihre bevorzugten Kontaktinformationen, damit wir Sie bei Rückfragen erreichen können. Anonyme Berichte werden ebenso bearbeitet, bergen jedoch das Risiko, bei offenen Rückfragen nicht angemessen bearbeitet werden zu können. -Benutzernamen der am Vorfall beteiligten Personen. -Ihre Schilderung des Vorfalls und ob Sie glauben, dass der Vorfall noch andauert. Wenn es eine öffentlich zugängliche Aufzeichnung gibt, geben Sie bitte den Link zur Prüfung des Vorfalls an. -Jede zusätzliche Information, die Ihrer Meinung nach hilfreich sein könnte. -Bitte verwenden Sie ausschließlich den oben genannten Kontakt, damit das zuständige Team auf Ihre Meldung reagieren kann. Ihre Angelegenheit wird mit Diskretion behandelt. Wir respektieren die Vertraulichkeit aller Anfragen zum Schutz der betroffenen Personen. +### 2. Warning -## 7. Lizenz und Quellenangaben +**Community Impact**: A violation through a single incident or series +of actions. -Der Code of Conduct wird unter der Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) Lizenz (https://creativecommons.org/licenses/by-sa/3.0/ [extern]) bereitgestellt. +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. -Wesentliche Quelle dieses Code of Conducts stammen von der OpenCoDE Plattform: https://wikijs.opencode.de/de/Hilfestellungen_und_Richtlinien/Code_of_Conduct +### 3. Temporary Ban -Textabschnitte dieses Code of Conduct sind inspiriert durch die Code of Conducts der Citizen Code of Conduct, Contributor Covenant, Open Source Initiative und der TODO Group. +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. ---------- +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. -## 1 Objective +### 4. Permanent Ban -The Code of Conduct serves as a valuable resource for our efforts to promote ethical conduct and deter unsavoury conduct within our community. +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. -The aim of the Code of Conduct for the Federal Architecture Directive is to integrate the widest possible range of people from the most diverse and varied backgrounds and to promote dialogue between them. We are committed to creating a friendly, safe and welcoming environment, regardless of gender and gender identity, sexual orientation, physical and mental ability, ethnic origin and nationality, religion and belief, age and social background, and social and economic status. +**Consequence**: A permanent ban from any sort of public interaction within +the community. -This Code of Conduct outlines our expectations of everyone who participates in our community and steps to report unacceptable behaviour. We invite everyone to join us in creating safe and positive experiences for all. +## Attribution -## 2 Scope +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. -We expect all contributors to abide by this Code of Conduct in all interactions with this community, whether online or in person. +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. -This Code of Conduct is not an exhaustive list of rules for friendly, safe and inclusive interaction in the community, but conveys our values and is intended as a guideline, reference point and inspiration for positive and valuable interaction for all. +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +at [https://www.contributor-covenant.org/translations][translations]. -## 3 Commitment to diversity - -We encourage all individuals to bring different perspectives to the project in compliance with this Code of Conduct. - -## 4 Our principles - -Together, we strive to contribute to the creation of a positive environment through our behaviour. As the primary mode of communication is in text form and therefore lacks the tone of voice, gestures or other context that is often crucial for understanding, it is particularly important that these positive behaviours are also conveyed in written communication. - -The following behaviours are expected and required of all participants: - -Be considerate of each other and treat each other with respect. -Use welcoming and inclusive language and choose words carefully. -Assume positive intentions from the other person. -Be patient and respect the time and attention of the community. -Focus on what is best for the community. -Actively promote dialogue and cooperation within the community. -Practice constructive criticism and accept it with grace. - -## 5 Unacceptable behaviour - -We do not accept behaviour that violates our Code of Conduct and are mindful of our surroundings and all participants. - -Please report any misbehaviour or violations of this Code of Conduct, even if they seem insignificant. - -The following behaviours are considered unacceptable and will not be tolerated in our community: - -Sexist, racist, homophobic, transphobic or otherwise discriminatory references, statements and language choices. -Personal insults, especially those relating to gender, sexual orientation, origin, religion, lifestyle or disability. -Intimidation, violence, threats of violence or violent language directed at another person. -Unwelcome sexually intrusive language or behaviour. -Posting or displaying sexual or violent material. -Persistent disruption of discussion. -Advocating or encouraging any of the above behaviours. -We cannot fully list all forms of unacceptable behaviour and harassment, nor do we attempt to declare some forms of it as harmless or not worthy of action. Rather, we ask you to report the incident if you feel harassed. The report will be handled discreetly and solutions will be sought without publicly addressing it in the forum, as this tends to exacerbate the problems for those affected and the community as a whole. - -## 6. Become active in case of violations - -Please take action and report any violation of the Code of Conduct. - -If you are affected by unacceptable behaviour, witness it or have other concerns, please report it directly: - -DGII3AG@bmi.bund.de - -We ask that your report includes the following: - -Your preferred contact information so that we can reach you if we have any questions. Anonymous reports will also be processed, but run the risk of not being able to be processed appropriately in the event of outstanding queries. -Usernames of the individuals involved in the incident. -Your account of the incident and whether you believe the incident is ongoing. If there is a publicly available record, please provide the link to review the incident. -Any additional information you feel may be helpful. -Please only use the contact above so that the appropriate team can respond to your report. Your matter will be dealt with discretion. We respect the confidentiality of all enquiries to protect the individuals concerned. - -## 7 Licence and references - -The Code of Conduct is provided under the Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) licence (https://creativecommons.org/licenses/by-sa/3.0/ [external]). - -The main source of this Code of Conduct comes from the OpenCoDE platform: https://wikijs.opencode.de/de/Hilfestellungen_und_Richtlinien/Code_of_Conduct - -Sections of this Code of Conduct are inspired by the Code of Conducts of the Citizen Code of Conduct, Contributor Covenant, Open Source Initiative and the TODO Group. \ No newline at end of file +[homepage]: https://www.contributor-covenant.org +[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..c77e51ad5197a650f0a41f15264483f2441a3a60 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing to the Document Writing Tools + +Thank you for your interest in contributing to the Document Writing Tools! We welcome contributions from everyone, whether you're a first-time contributor or a long-time friend. This document will help you get started with the project. + +## Contributor License Agreement (CLA) + +Before we can accept your contributions, we need a signed version of a Contributor License Agreement (CLA) from you. Please download the template from here: [CLA_en.pdf](https://gitlab.opencode.de/open-code/document-writing-tools/document-writing-ci-components/-/blob/main/CLA/CLA_en.pdf). Fill out the CLA and email the signed copy back to us. + +Please send the signed CLA to the following email address: ***hello@zendis.de***. + +As soon as we have received the Contributor License Agreement from you, we will be able to accept your contributions. + +## Code of Conduct + +We have a [Code of Conduct](CODE_OF_CONDUCT.md) that we expect all contributors to follow. Please read it before contributing. + +## How to Contribute + +You can contribute to the Badge API in many ways. Here are some examples: + +- Reporting a bug +- Fixing a bug +- Adding a new feature +- Improving the documentation +- Writing tests +- Reviewing code +- Helping others in the community + +## Contributing code + +### Outline + +1. Create [an openCode account](https://opencode.de/en/register) +2. Fork the repository +3. Clone the repository +4. Create a new branch +5. Make your changes +6. Push your changes to your fork +7. Create a merge request +8. Address any feedback + +## Updating Docs + +Please refer to the documentation project [here](https://gitlab.opencode.de/open-code/document-writing-tools/gitlab-profile). \ No newline at end of file diff --git a/LICENSE.spdx b/LICENSE.spdx new file mode 100644 index 0000000000000000000000000000000000000000..0645cf903423fcbba0f8c33a3ecb3ae46e23e741 --- /dev/null +++ b/LICENSE.spdx @@ -0,0 +1,6 @@ +SPDXVersion: SPDX-2.0 +DataLicense: CC0-1.0 +PackageName: badge-api +PackageOriginator: Bundesministerium des Innern und für Heimat, AG DG II 3 - Strategie; IT-Architektur; Standards; Gemeinsame IT Bund +PackageHomePage: https://gitlab.opencode.de/open-code/document-writing-tools/document-writing-ci-components +PackageLicenseDeclared: EUPL-1.2 \ No newline at end of file diff --git a/README.md b/README.md index 4aea6cbb1bc778e99f1e0dd05aab3fea1e4f62d3..4d6cf1e8c9e6052e31fbdf09f70c286d6e733e42 100644 --- a/README.md +++ b/README.md @@ -29,176 +29,48 @@ ## Table of Contents - [Table of Contents](#table-of-contents) - [Overview](#overview) -- [PDF UA Generation Component](#pdf-ua-generation-component) - - [Inputs](#inputs) - - [Usage](#usage) - - [Customization](#customization) - - [Modifying the LaTeX Template](#modifying-the-latex-template) - - [Adding Accessibility Tags](#adding-accessibility-tags) - - [Markdown Examples for Accessibility Tags](#markdown-examples-for-accessibility-tags) -- [Markdown Quality Check Component](#markdown-quality-check-component) - - [Inputs](#inputs-1) - - [Usage](#usage-1) - - [Running the Pipeline](#running-the-pipeline) -- [Markdown Webview Component](#markdown-webview-component) - - [Inputs](#inputs-2) - - [Usage](#usage-2) - - [Running the Pipeline](#running-the-pipeline-1) +- [Usage](#usage) - [Contributing](#contributing) - [Support](#support) +- [License](#license) --- ## Overview -This project provides GitLab CI/CD components for processing Markdown files into PDFs, validating Markdown quality, and creating webviews. The components include: +This project provides GitLab CI/CD components for processing Markdown files into PDFs, validating Markdown quality, and creating web views. The components include: 1. **PDF UA Generation Component:** Converts Markdown files to PDF while ensuring PDF/UA compliance. 2. **Markdown Quality Check Component:** Validates the quality of Markdown files, including link reachability, and provides GitLab Code-Quality widgets. -3. **Markdown Webview Component:** Generates a webview of Markdown files and pushes the resulting container to a registry. +3. **Web View Light Component:** Generate a web view of Markdown files and publish the result as a GitLab page. +4. **Web View Full Component:** Generate a web view of Markdown files and pushes the resulting container to a registry with additional features. -These components are used in the `architekturrichtline-bund` repository as an example. +These components are used in the [IT-Architekturrichtlinien](https://gitlab.opencode.de/it-architekturrichtlinien) repositories as an example. ---- - -## PDF UA Generation Component - -This component generates accessible PDF files from Markdown with customizable LaTeX templates and PDF/UA compliance. - -### Inputs - -| Input | Default | Description | -|------------------|---------------|--------------------------------------------------------------| -| `stage` | `build` | The stage where the job should be executed | -| `md-path` | `document` | The path to the Markdown directory (e.g., `test-document/document`) | -| `template-path` | `template` | The path to the template directory (e.g., `test-document/template/`) | -| `outputfile-name` | None | The name of the output file | -| `document-title` | `Document` | The title of the document | -| `primary-color` | `0.12,0.28,0.49` | The primary color of the document in RGB 0-1 | -| `mode` | `full` | Mode of the pdf generation, one of ['full','compact','core'] | -| `additional-controls-highlighting` | `false` | Highlight additional controls in the pdf (currently only for full mode) | - -### Usage - -Include the following configuration in your `.gitlab-ci.yml` file: - -```yaml -- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/md-to-pdf-ua@$CI_COMMIT_SHA - inputs: - stage: build - md-path: test-document/document - template-path: test-document/template/ - outputfile-name: test -``` - -### Customization - -#### Modifying the LaTeX Template -The LaTeX template in `templates/template.tex` serves as a base for your PDF. Update the file to change styles, fonts, headers, footers, and other formatting elements. - -#### Adding Accessibility Tags -To maintain PDF/UA compliance, ensure your Markdown and LaTeX template include: -- Semantic headings. -- Alternative text for images. -- Correct table structures. - -#### Markdown Examples for Accessibility Tags - -1. **Semantic Headings:** Use proper heading levels to create a clear document structure. - ```markdown - # Main Title - ## Section Title - ### Subsection Title - - Content under the subsection. - ``` - -2. **Alternative Text for Images:** Provide descriptive text for images. - ```markdown -  - ``` - -3. **Accessible Tables:** Use proper Markdown syntax for tables with headers. - ```markdown - | Column 1 | Column 2 | Column 3 | - |----------|----------|----------| - | Data 1 | Data 2 | Data 3 | - ``` - -Refer to [PDF/UA Best Practices](https://www.pdfa.org/resource/what-is-pdfua/) for more details. - ---- - -## Markdown Quality Check Component - -This component validates the quality of Markdown files, checking for issues like broken links and providing feedback via GitLab Code-Quality widgets in merge requests. - -### Inputs - -| Input | Default | Description | -|------------|---------------|--------------------------------------------------| -| `stage` | `build` | The stage where the job should be executed | -| `md-path` | `document` | The path to the Markdown directory (e.g., `test-document/document`) | - -### Usage - -Include the following configuration in your `.gitlab-ci.yml` file: - -```yaml -include: -- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/md-quality@$CI_COMMIT_SHA - inputs: - stage: test - md-path: test-document/document -``` - -### Running the Pipeline -1. Add your Markdown files to the repository. -2. Push your changes to trigger the GitLab pipeline. -3. The pipeline will validate the quality of the Markdown files, ensuring all links are reachable and providing feedback via GitLab Code-Quality widgets in merge requests. +Happy PDF building, Markdown validation, and webview generation with GitLab CI/CD! --- +## Usage -## Markdown Webview Component - -This component generates a webview of Markdown files and pushes the resulting container to the GitLab container registry. - -### Inputs - -| Input | Default | Description | -|------------------|---------------|--------------------------------------------------------------| -| `md-path` | `document` | The path to the Markdown directory (e.g., `document`). **Needs to contain assets folder - even if empty!** | -| `template-path` | `template` | The path to the template directory (e.g., `template`) | - -### Usage - -Include the following configuration in your `.gitlab-ci.yml` file: - -```yaml -- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/md-to-web@$CI_COMMIT_SHA - inputs: - md-path: test-document/document # needs to contain assets folder - even if empty! - template-path: test-document/template -``` - -### Running the Pipeline -1. Commit your Markdown files and templates to your repository. -2. Push your changes to trigger the GitLab pipeline. -3. The pipeline will generate a webview of your Markdown files and push the container to the GitLab container registry. +Please refer to the [documentation](https://gitlab-profile-40b1a6.usercontent.opencode.de/) for detailed instructions on using the components. --- ## Contributing Contributions are welcome! Please: -- Fork the repository. -- Create a feature branch. -- Submit a merge request with a clear description of your changes. +- Read the [Contributing Guidelines](CONTRIBUTING.md). +- Sign the [Contributor License Agreement](CLA/CLA_en.pdf). +- Follow the [Code of Conduct](CODE_OF_CONDUCT.md). --- ## Support If you encounter issues or have questions, please open an issue in this repository or contact the maintainers. +- [Report a Bug](https://gitlab.opencode.de/open-code/document-writing-tools/document-writing-ci-components/-/issues/new?issuable_template=bug) +- [Request a Feature](https://gitlab.opencode.de/open-code/document-writing-tools/document-writing-ci-components/-/issues/new?issuable_template=feature) + --- -Happy PDF building, Markdown validation, and webview generation with GitLab CI/CD! +## License +This project is licensed under the EUPL 1.2. See the [LICENSE.md](LICENSE.md) file for details. \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md index 126f6ed5fcce5ccd62de931d1ba91d872bef7688..f0979c9e9c4424fc509bf88bcd3bdace74d240ad 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -10,12 +10,13 @@ This document outlines security procedures and general policies for this project ## Disclosing a security issue -The projects maintainers take all security issues in the project +The project's maintainers take all security issues in the project seriously. Thank you for improving the security of this project. We appreciate your dedication to responsible disclosure and will make every effort to acknowledge your contributions. -We leverage opening a [Confidential Issue](https://gitlab.opencode.de/archrl-it-bund/document-writing-ci-components/-/issues/new?confidential=true). +- You can send your report to the following e-mail address: [security@zendis.de](mailto:security@zendis.de) +- You can open a [Confidential Issue](https://gitlab.opencode.de/open-code/document-writing-tools/document-writing-ci-components/-/issues/new?issue[confidential]=on&issuable_template=security-advisory) Here are some helpful details to include in your report: @@ -24,8 +25,8 @@ Here are some helpful details to include in your report: - versions of the project that may be affected by the issue - if known, any mitigations for the issue -A maintainer will acknowledge the report within five (3) business days, and -will send a more detailed response within an additional five (3) business days +A maintainer will acknowledge the report within five (5) business days, and +will send a more detailed response within an additional five (5) business days indicating the next steps in handling your report. After the initial reply to your report, the maintainers will endeavor to keep @@ -47,7 +48,7 @@ following steps: ## Suggesting changes -If you have suggestions on how this process could be improved please submit an +If you have suggestions on how this process could be improved, please submit an issue or pull request. ## Acknowledgements