diplodoc-platform / diplodoc Goto Github PK

Using an undefined variable is not expected to yield a warning if its occurrence is hidden behind a conditional operator. But this doesn't work when the variable is used inside a code block (```).

See the example gist.

Allow to add new project to diplodoc service in three steps

• Authorise with github
• Create new gh repo from diplodoc-template
• Register new project in diplodoc system for created gh repo
• Register new project in diplodoc system for existed gh repo
• Fill initial info on project s3 bucket

• Move server implementation to diplodoc-platform organisation
• Describe server installation and usage in docs

Ready github action for simple include the render of documentation for CI process at github.

In ideal way - with simple integration with github pages.

This works fine:

title: Test document
items:
  - name: Index
    href: index.md
  - name: External article
    href: https://example.com

But when you create a variable for the URL, url: https://example.com, and use it in the href value, there's an error:

title: Test document
items:
  - name: Index
    href: index.md
  - name: External article
    href: "{{ url }}"

No such file or has no access to /home/glunchadze/diplodoc-test-gen/.tmp_input/{{ url }}.md Error: ENOENT: no such file or directory, open '/home/glunchadze/diplodoc-test-gen/.tmp_input/{{ url }}.md'
    at Object.openSync (node:fs:603:3)
    at readFileSync (node:fs:471:35)
    at /home/glunchadze/.nvm/versions/node/v18.18.2/lib/node_modules/@diplodoc/cli/build/index.js:2140:49
    at Generator.next (<anonymous>)
    at /home/glunchadze/.nvm/versions/node/v18.18.2/lib/node_modules/@diplodoc/cli/build/index.js:78:61
    at new Promise (<anonymous>)
    at __async (/home/glunchadze/.nvm/versions/node/v18.18.2/lib/node_modules/@diplodoc/cli/build/index.js:62:10)
    at resolveMd2HTML (/home/glunchadze/.nvm/versions/node/v18.18.2/lib/node_modules/@diplodoc/cli/build/index.js:2130:10)
    at /home/glunchadze/.nvm/versions/node/v18.18.2/lib/node_modules/@diplodoc/cli/build/index.js:2969:12
    at Generator.next (<anonymous>) {
  errno: -2,
  syscall: 'open',
  code: 'ENOENT',
  path: '/home/glunchadze/diplodoc-test-gen/.tmp_input/{{ url }}.md'
}

ERR No such file or has no access to /{{ url }}.md

When one file, say wo-endcut.md, has a {% cut "..." %} without an {% endcut %}, and another file, say index.md, has a link to it with title substitution ([{#T}](...)), the endcut error shows up not only for the first file, but for both:

ERR Cut must be closed in /index.md
ERR Cut must be closed in /wo-endcut.md

See the gist for examples of this and #9.

The endcut error should only show up for the file with the cut.

I have .md file:

# Описание папок в src и проектов в них

В папке **src** находится исходный код микросервисов, модулей и вспомогательных библиотек ... .

![](../_images/structure.png)

## Extras

Папка, cодержащая вспомогательные библиотеки, используемые для поддержки мультиязычности в библиотеках вьювера.

...... - фронтэнд библиотека для сбора локалей и поддержки мультиязычности в библиотеках вьювера.

## Tangl

Содержит библиотеки вьювера.

### Вьювер

- ......  - библиотека вьювера.

and toc.yaml file

title: ....
href: index.yaml;
navigation:
  logo:
    url: '../tangl'
  header:
    leftItems:
      - text: 'Item..'
        type: 'link'
        #url: '../../how-to/'
      - text: 'Item...'
        type: 'link'
        #url: '../../docs/ru/'
items:
  - name: CHANGELOG
    href: CHANGELOG.md
  - name: Разделы
    expanded: true
    items:
      - name: Структура
        href: structure.md

run this command yfm -i ./docs -o ./output

and i have generated object with assets, which has absolute path for images in assets list

{ "data": { "leading": false, "toc": { "title": "Tangl", "href": "index.html", "navigation": { "logo": { "url": "../tangl" }, "header": { "leftItems": [ { "text": "Item..", "type": "link" }, { "text": "Item...", "type": "link" } ] } }, "items": [ { ..... }, { ..... }, { "name": "Разделы", "expanded": true, "items": [ ...... ], "id": "Разделы-2-0.2943391760813012" } ], "base": "...." }, "meta": { "metadata": [], "style": [], "script": [] }, "assets": [ "/home/..../www/work/test/output/.tmp_input/_images/structure.png" ], "headings": [ { "title": "Extras", "href": "#extras", "level": 2 }, { "title": "....", "href": "#...", "level": 2, "items": [ { "title": "Вьювер", "href": "#vyuver", "level": 3 } ] } ], "title": "Описание папок в src и проектов в них", "includes": [], "html": "...." }, "router": { "pathname": "structure.html" } }

In the result paths point to tmp folder which will be deleted after build process which is an unexpected behavior

But... my html generated correctly <img src="../_images/tangl-structure.png" />

• Move yfm2pdf package to diplodoc-platform organisation
• Describe usage in documentation

Hello! I recently had an idea to compare different libraries/services that one can use to search docs or any kind of texts. For this purpose, I created a search index in opensearch, flexsearch and lunr.js and tested them all on several searches.

The source index consists of 1136 entries with title, short description and full content. The content contains documentation on various topics, but mostly cloud related. All three libraries/services were set up to search within these three fields.

Here's the link to the document, where I provided all the data I ended up with.

Let me know if you need more info!

Diplodoc docs do not forbid empty cuts. But building a document with an cut which is made empty (intentionally or not, e.g. when none of conditional operators inside the cut return true) results in an error, seemingly irrelevant:

ERR Cut must be closed in /w-endcut.md

See the gist for examples of this and #10.

Empty cuts should either be allowed or result in their own error.

Steps

1. open https://diplodoc.com
2. sart
3. Authorization via github
4. Allow on github side
5. after redirect to diplodoc...

Could not get github state back

Allow to translate initial documentation to other languages in automatic or semi automatic mode

• Implement CommonMark translation fragments extraction and composition
• Implement YFM translation fragments extraction and composition
• Implement precise inline markdown wrapping
• Implement automatic translation API
  • Add documentation
  • Add tutorial for Yandex Translation API
  • Improve CLI integration
• Implement semi automatic translation API
  • Add documentation
  • Add tutorial for SmartCat system
  • Improve CLI integration
• Implement json translation for toc.yaml and any other json-schema described format

Integrate page-constructor in static client

This allows to draw custom header in static documentation.

• Implement page-constructor navigation drawing in client package
• Implement navigation config in toc.yaml in cli package
  • Inline configuration
  • configuration separated in external file
  • cascade configuration
• Write documentation in docs package

This repository serves as unified point to community issues, discussions, announces etc.

• Link main packages to metapackage
• Add LICENCE to all packages
• Add initial development infrastructure
• Describe CONTRIBUTION.md and DEVELOPMENT.md
• Describe README.md