Merge pull request #597 from DocHubTeam/md-in-manifest

v3.14.0

Author: rpiontik

distrib/idea/IDEAPlugin-4.1.7.zip renamed to distrib/idea/IDEAPlugin-4.2.0.zip

@@ -0,0 +1,14 @@
+---
+docs:
+    dochub.example.markdown.metadata:
+        title: Пример Markdown с включенным архитектурным манифестом
+        location: /test
+        type: markdown
+        source: .
+    dochub.example.markdown.metadata2:
+        title: Пример Markdown с включенным архитектурным манифестом
+        location: /test2
+        type: markdown
+        source: .
+---
+# Hello world!

public/documentation/docs/manual/docs/examples/inlinemeta.md

@@ -27,6 +27,29 @@
 
 ![Кот](examples/cat.jpg)
 
+### Архитектурный манифест в теле документа
+
+Рекомендуется использовать данную функциональность с осторожностью, так как стандарт Markdown не предусматривает включение метаданных в документ.
+Тем не менее, многие инструменты поддерживают такую возможность. DocHub добавил поддержку метаданных в Markdown, начиная с версии v3.14.0.
+
+Блок метаданных в теле документа начинается с трех тире "---" и заканчивается также ими "---". Пример документа:
+
+```
+---
+docs:
+    dochub.example.markdown.metadata:
+        title: Пример Markdown с включенным архитектурным манифестом
+        type: markdown
+        source: .
+---
+# Hello world!
+```
+
+Пример демонстрирует встраивание архитектурного манифеста в тело Markdown-документа. В данном случае манифест включает описание документа
+и ссылку на его содержимое в том же файле. Путь к текущему документу обозначается как точка ".".
+
+Метаданные документ могут включать любой контент допустимый для архитектурного манифеста. 
+
 ### Ссылки на объекты DocHub
 Добавляет ссылку на архитектурный объект. Пример для ссылки на документ:
 ```

public/documentation/docs/manual/docs/markdown.md

@@ -31,7 +31,7 @@ Contributors:
 import logger from '../utils/logger.mjs';
 import request from '../helpers/request.mjs';
 import {getRoles} from '../helpers/jwt.mjs';
-import {getCurrentRuleId, getCurrentRules} from "../utils/rules.mjs";
+import {getCurrentRuleId, getCurrentRules} from '../utils/rules.mjs';
 
 const LOG_TAG = 'controller-storage';
 
@@ -47,8 +47,8 @@ export default (app) => {
         const hash = req.params.hash || '$unknown$';
         const url = req.originalUrl.slice(`/core/storage/${hash}/`.length).replace(/\%E2\%86\%90/g, '..');
         //const url = decodeURIComponent(req.params.url);
-        const uri = url.split('?')[0];
         const baseURL = app.storage?.md5Map[hash];
+        const uri = url.split('?')[0] || baseURL;
         logger.log(`Request to storage ${req.originalUrl}`, LOG_TAG);
         if (!baseURL || !uri) {
             res.status(403).json({
@@ -62,4 +62,4 @@ export default (app) => {
                 }));
         }
     });
-};
+};

src/backend/controllers/storage.mjs

@@ -41,7 +41,7 @@ import '../helpers/env.mjs';
 
 import jsonataDriver from '../../global/jsonata/driver.mjs';
 import jsonataFunctions from '../../global/jsonata/functions.mjs';
-import {newManifest, loader, isRolesMode, DEFAULT_ROLE} from "../utils/rules.mjs";
+import {newManifest, loader, isRolesMode, DEFAULT_ROLE} from '../utils/rules.mjs';
 
 const LOG_TAG = 'storage-manager';
 
@@ -96,7 +96,7 @@ export default {
 				for(let nRule in manifest?.roles) {
 					if(app.new_rules[rule] === nRule) {
 						mergeRules = mergeRules.concat(manifest?.roles[nRule]);
-						ids.push(nRule)
+						ids.push(nRule);
 					}
 				}
 			}
@@ -113,7 +113,7 @@ export default {
 		// Загрузку начинаем с виртуального манифеста
 		cache.errorClear();
 		let storageManifest = {};
-		let createManifest = async function() {
+		let createManifest = async() => {
 			await manifestParser.clean();
 			await manifestParser.startLoad();
 			await manifestParser.import('file:///$root$');
@@ -122,7 +122,7 @@ export default {
 			await manifestParser.stopLoad();
 		};
 
-		let createRoleManifest = async function () {
+		let createRoleManifest = async() => {
 			try {
 				// загружаю основной файл с ролями
 				const {URI} =  global.$roles;
@@ -139,9 +139,9 @@ export default {
 					storageManifest.manifests[role] = newManifest(storageManifest.manifests.origin, exclude, filters);
 				}
 			} catch (e) {
-				this.registerError(e, e.uri || uri);
+				this.registerError(e, e.uri);
 			}
-		}
+		};
 
 		await createManifest();
 

src/backend/storage/manager.mjs

@@ -213,6 +213,10 @@
               content = mustache.render(data, this.source.dataset);
             } else
               content = data;
+            // Извлекаем документ отделяя от метаданных если они есть
+            const parts = content.split('---');
+            if (parts.length === 3 && !parts[0])
+              content = content.split('---').pop(); 
             this.markdown = this.prepareMarkdown(content);
           }).catch((e) => {
             this.error = e;

src/frontend/components/Docs/DocMarkdown.vue

@@ -168,6 +168,7 @@ export default {
         },
         url() {
             let uri = this.profile.template || this.profile.source;
+            if (uri === '.') uri = this.contentBasePath;
             uri?.startsWith('res://') && (uri = requests.expandResourceURI(uri));
             let result = this.profile ? uriTool.makeURIByBaseURI(uri, this.contentBasePath).toString() : null;
             if (!result) return null;

src/frontend/components/Docs/DocMixin.js

@@ -32,7 +32,7 @@
 import * as semver from 'semver';
 import cache from './services/cache.mjs';
 import prototype from './prototype.mjs';
-
+import yaml from 'yaml';
 
 class PackageError extends Error {
 	constructor(uri, message) {
@@ -374,12 +374,18 @@ const parser = {
 	},
 
 	async import(uri) {
-		console.log('import.uri',uri);
+		console.log('import.uri', uri);
 		try {
 			const response = this.onPullSource 
 				? await this.onPullSource(uri, '/', this)
 				: await parser.cache.request(uri, '/');
-			const manifest = response && (typeof response.data === 'object'
+			let manifest;
+			if (uri.toLowerCase().endsWith('.md')) {
+				const parts = response.data.split('---');
+				if (parts.length === 1) manifest = {};
+				else if (parts.length !== 3) throw new Error('Incorrect metadata of markdown file');
+				else manifest = yaml.parse(parts[1]);
+			} else manifest = response && (typeof response.data === 'object'
 				? response.data
 				: JSON.parse(response.data));
 

src/global/manifest/parser.mjs

@@ -34,6 +34,7 @@
 import cache from './services/cache.mjs'; // Сервис управления кэшем
 import * as semver from 'semver'; // Управление версиями  
 import prototype from './prototype.mjs';
+import yaml from 'yaml';
 
 // Кладовка
 // https://github.com/douglascrockford/JSON-js
@@ -458,7 +459,12 @@ parser.pushRequest = function(uri, owner) {
         request.then((response) => {
             // Удаляем из загрузок ресурс
             delete parser.sourceLoading[uri];
-            success(response && (typeof response.data === 'object'
+            if (response.headers?.['content-type'].match(/^.*\/markdown($|;.*$)/)) {
+                const parts = response.data.split('---');
+                if (parts.length === 1) success({});
+                else if (parts.length !== 3) reject(new Error('Incorrect metadata of markdown file'));
+                else success(yaml.parse(parts[1]));
+            } else success(response && (typeof response.data === 'object'
                 ? response.data
                 : JSON.parse(response.data))
             );