{"id":28861538,"url":"https://github.com/vivarado/includoc","last_synced_at":"2025-07-07T06:36:41.923Z","repository":{"id":296050782,"uuid":"991819590","full_name":"VivaRado/IncluDoc","owner":"VivaRado","description":"IncluDoc inclusive and multilingual Markdown documentation!","archived":false,"fork":false,"pushed_at":"2025-05-29T09:26:00.000Z","size":1021,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-20T06:02:43.345Z","etag":null,"topics":["documentation","generator","include","markdown","md","multilingual"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VivaRado.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-28T07:40:05.000Z","updated_at":"2025-05-29T14:32:40.000Z","dependencies_parsed_at":"2025-05-28T19:47:41.633Z","dependency_job_id":"e35386ab-3a36-4cda-b734-5359d8ea85e7","html_url":"https://github.com/VivaRado/IncluDoc","commit_stats":null,"previous_names":["vivarado/includoc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VivaRado/IncluDoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VivaRado%2FIncluDoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VivaRado%2FIncluDoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VivaRado%2FIncluDoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VivaRado%2FIncluDoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VivaRado","download_url":"https://codeload.github.com/VivaRado/IncluDoc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VivaRado%2FIncluDoc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260891087,"owners_count":23077906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","generator","include","markdown","md","multilingual"],"created_at":"2025-06-20T06:01:04.363Z","updated_at":"2025-07-07T06:36:41.916Z","avatar_url":"https://github.com/VivaRado.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"## **Preface**\n\n**IncluDoc** is an Open Source project of **VivaRado**.\n\n\u003cdiv markdown='1' class=\"header_logo\"\u003e\n\n![Screenshot](./_README/assets/media/includoc_logo.svg)\n\n\u003c/div\u003e\n\n\n \n##  **Introduction**\n\n**IncluDoc** inclusive and multilingual Markdown documentation!\n\n#### Contributors:\n\n*  VivaRado support@vivarado.com\n*  Andreas Kalpakidis\n*  Madina Akhmatova\n\n\n---\n\n### **Profile**\n\u003csub\u003eIntroduction / Profile\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\n\n*  Company: VivaRado LLP\n*  Designer: Andreas Kalpakidis\n*  Management: Madina Akhmatova\n\n---\n\n\n### **Project Overview**\n\u003csub\u003eIntroduction / Project Overview\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\n*   Project Name: IncluDoc\n*   Code Name: IncDoc\n*   Proposal Date: 28/05/2025\n\n---\n\n\n### **Design**\n\n\nIncluDoc gathers Markdown files, handles include statements and generates a main README.md and/or a multilingual README.html with a user interface.\n\nA file can have alternatives and you can choose which gets included and compiled.\n\nThe user interface and SVG on the documents are designed to work with ```prefers-color-scheme: dark``` and react to dark and light mode.\n\n\n\n---\n\n### **Installation**\n\n\nPrerequisites:\n\n* The compilation of the **Markdown** files relies on **Python** and libraries **Markdown2** and **lxml**. \n* The HTML user interface uses **emphase** to highlight code elements, already included in the ```assets/vendors```, you might need to include some language files a the footer of ```Lib/html_template.py``` in case you need to render more languages.\n\n\n#### Install Python Requirements:\n\nTo install python requirements from the ```requirements.txt```, run this command:\n\n```pip install -r Lib/requirements.txt```\n\nor install each dependency package manually:\n\n* lxml\n* Markdown2\n\n\n---\n\n### **Usage**\n\n\nPrepare and organise your files into directories within ```/lang``` and compile with parameters bellow.\n\n---\n\n### **Parameters**\n\u003csub\u003eUsage / Parameters\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\n\nPass the parameters during python file execution.\n\n```\npython3 './_README/gen_readme.py' --format 'html,md' --alter 'M0'\n```\n\n---\n\n#### Parameter Overview\n\nA description of each parameter:\n\n\u003cbr\u003e\n\n**--format** [ String ]\n\u003e \n\u003e Provide the generated format string, supported formats: ```'html'``` ```'md'``` \n\n\u003cbr\u003e\n\n**--alter** [ String ]\n\u003e \n\u003e Provide the alternative files to look for inclusion, suggested structure is a letter and a number like ```A0, A1 ...```\n\n---\n\n### **Includes**\n\u003csub\u003eUsage / Includes\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\n\nYou can include MD files from within MD files by providing an **inline** MarkDown **code block** with special parameters. Grave accents ` are enclosed (```) in the examples bellow, we need them disclosed in the actual markdown.\n\n```\n(```){include=partials/profile_project.md}(```)\n```\n\nTo provide an alternative for the include:\n\n```\n(```){include=partials/profile_project.md,M0}(```)\n```\n\nThe alternative priority is described here: ```Templates / Structure```.\n\n---\n\n### **Ignores**\n\u003csub\u003eUsage / Ignores\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\nYou can create .gitignore and .npmignore to avoid publishing any uncompiled markdown files. For example:\n\n```\n# .gitignore\n_README/__pycache__/\n_README/addons/\n_README/lang/\n_README/Lib/\n_README/*.py\n_README/*.txt\n_README/version\n_README/*.html\n_README/*.sh\n_README/assets/css/\n_README/assets/js/\n_README/assets/vendor/\n```\n\n---\n\n### **Vendors**\n\n\nHere are examples of some popular vendors in this readme.\n\n---\n\n#### MermaidJS\n\nMermaidJS for various graphs and schedules.\n\n\u003cbr\u003e\n\n```mermaid\npie title Documentation\n\t\"Time spent writing code\" : 10\n\t\"Time spent documenting it\" : 90\n```\n\n---\n\n#### FlowchartJS\n\nFlowchartJS for flowcharts.\n\n\u003cbr\u003e\n\n```flowchart\nst=\u003estart: Start:\u003ehttp://www.vivarado.com[blank]\ne=\u003eend:\u003ehttp://www.vivarado.com\nop1=\u003eoperation: My Operation\nsub1=\u003esubroutine: My Subroutine\ncond=\u003econdition: Yes\nor No?:\u003ehttp://www.vivarado.com\nio=\u003einputoutput: catch something...\npara=\u003eparallel: parallel tasks\nin=\u003einput: some in\nout=\u003eoutput: some out\n\nst-\u003eop1-\u003econd\ncond(yes)-\u003eio-\u003ee\ncond(no)-\u003epara\npara(path1, bottom)-\u003esub1(right)-\u003eop1\npara(path2, top)-\u003eop1\npara(path3, right)-\u003ein-\u003eout-\u003ee\n```\n\n\n---\n\n### **Templates**\n\n\nTemplating is versatile and easy, allows for custom structures and includes. We hope to add some templates in the near future.\n\n---\n\n### **Structure**\n\u003csub\u003eTemplates / Structure\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\nIt is important to maintain a couple of things in order to be able to use IncluDoc.\n\n\n#### Hierarchy:\n\nThe interactive user interface uses the H3 wrapped category titles, in combination with the contents hierarchy, for navigation. That is why you should match what you have in your contents file (that will end up as the sidebar) and your content header titles.\n\ne.g.:\n\nAssuming this is in your **contents.md**:\n\n```\n1.  **Introduction**\n    1.  **Profile**\n    \t1.  **Contributors**\n    1.  **Project Overview**\n```\n\nYour **document.md** should have these headers:\n\n\n```plaintext\n**Introduction**\n\n**Introduction / Profile**\n\n**Introduction / Profile / Contributors**\n\n**Introduction / Project Overview**\n```\n\n#### Priority:\n\nThe files in each language directory within ```/lang```, and no deeper. Are included in order of enumeration.\n\n```\n000_preface\n001_contents\n002_document\n003_footer\n```\n\n#### Alternatives:\n\nDuring generation, you can input the alternative you prefer to be included, using the parameter ```--a``` or ```--alter```. This will allow for alternative versions of files to be selected for compilation. The selection priority is to select the file requested with the ```--alter``` parameter, if that file does not exist, then select the default version of that file.\n\ne.g.:\n\nAssuming your ```--alter``` parameter is ```M1```, here is the result on your files:\n\n```\n000_M1_preface:\n\t\u003e would be selected because it is a requested alternative.\n\n000_preface:\n\t\u003e would be ignored because it is the default and there is an alternative found.\n\n001_M0_contents:\n\t\u003e would be ignored because it is a different alternative.\n\n001_contents:\n\t\u003e would be selected because it is the default and the alternative requested was not found.\n```\n\n---\n\n### **Multilingual**\n\u003csub\u003eTemplates / Multilingual\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\nGenerate multilingual documentation, with a user interface.\n\n\n#### Multilingual Directories:\n\nIncluDoc will gather every language directory within ```/lang``` compile and combine that into separate MD documents, placed in those directories as ```README_collected_{lang}.md```.\n\nThe HTML version of the docs after generating will appear in ```_README/README.html``` with a user interface to toggle between the languages.\n\n\n---\n\n\n### **Glossary**\n\n\nN/A\n\n\n---\n\n\n### **Reference**\n\n\n[**Markdown2**](https://pypi.org/project/markdown2/)\u003cbr\u003e\n[**lxml**](https://pypi.org/project/lxml/)\u003cbr\u003e\n[**MermaidJS**](https://mermaid.js.org/)\u003cbr\u003e\n[**FlowchartJS**](https://flowchart.js.org/?lng=en)\u003cbr\u003e\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivarado%2Fincludoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvivarado%2Fincludoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivarado%2Fincludoc/lists"}