Merge pull request #8 from bem/#7

Add custom renderer for parsing markdown documents
bem-site · Jul 30, 2014 · 7c91c83 · 7c91c83
2 parents 6e098d1 + 4f17110
commit 7c91c83
Show file tree

Hide file tree

Showing 3 changed files with 124 additions and 62 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@ bem-data-source
 
 Инструмент для версионированной сборки документации и примеров библиотек для проектов bem-info legoa-www.
 
-### Установка
+## Установка
 
 * клонировать репозиотрий `git clone git://github.com/bem/bem-data-source.git`
 * перейти в директорию с выкачанным проектом `cd bem-data-source`
@@ -12,15 +12,15 @@ bem-data-source
 Команда `make` устанавливает зависимости для проекта и генерирует конфигурационный файл:
 * `config/credentials.json`
 
-### Конфигурирование
+## Конфигурирование
 
 Конфигурация инструмента описывается в файлах `config/config.json`, `config/credentials.json`.
 
-##### `config/config.json`
+#### `config/config.json`
 
 * `logLevel` - флаг уровня логгирования.
 
-##### `config/credentials.json`
+#### `config/credentials.json`
 
 Файл с токенами доступа к публичным и приватным репозиториям (github.com и github.yandex-team.ru соответственно)
 Необходимо сгенерировать токены доступа в настройках профиля пользователя на github.com и github.yandex.team.ru
@@ -51,7 +51,7 @@ bem-data-source
 }
 ```
 
-##### Файл `config/pattern.js`
+#### Файл `config/pattern.js`
 
 В этом файле описываются для каждой библиотеки можно переопределить дефолтные настройки сборки, например:
 
@@ -60,73 +60,88 @@ bem-data-source
     builder: 'enb',
     command: 'YENV=production enb make tests && enb make docs',
     copy: ['*.docs', '*.tests'],
-    readme: {
-        folder: '',
-        pattern: 'README.md'
-    },
-    changelog: {
-        folder: '',
-        pattern: 'CHANGELOG.md'
-    },
-    migration: {
-        folder: '',
-        pattern: 'MIGRATION.md'
-    },
-    notes: {
-        folder: '',
-        pattern: 'MIGRATION.md'
-    }
-    pattern: {
-        data: '%s.data.json',
-        jsdoc: '%s.jsdoc.html'
-    },
+    docs: {
+        readme: {
+            folder: '',
+            pattern: 'README.md'
+        },
+        changelog: {
+            folder: '',
+            pattern: 'CHANGELOG.md'
+        },
+        migration: {
+            folder: '',
+            pattern: 'MIGRATION.md'
+        },
+        notes: {
+            folder: '',
+            pattern: 'MIGRATION.md'
+        }
+        pattern: {
+            data: '%s.data.json',
+            jsdoc: '%s.jsdoc.html'
+        },
+    },    
     skip: []
 }
 ```
 
 Здесь:
 
-* `builder` - название инструмента с помощью которого будет выполняться сборка документации и примеров.
- Допустимые значения `enb` и `bem-tools`. 
- Значение по умолчанию `bem-tools`.
-
-* `command` - строка с названием команды для запуска сборки. 
- Значение по умолчанию `npm run build`
+##### builder 
+Название инструмента с помощью которого будет выполняться сборка документации и примеров.
 
-* `copy` - массив с шаблонами названий директорий с файлами документации и примеров, 
-которые должны попасть в финальный результат сборки. Первым элементом данного массива должен быть шаблон директорий
+Допустимые значения `enb` и `bem-tools`. 
+Значение по умолчанию `bem-tools`.
+
+##### command 
+Cтрока с названием команды для запуска сборки. 
+Значение по умолчанию `npm run build`
+
+##### copy 
+Массив с шаблонами названий директорий с файлами документации и примеров, 
+которые должны попасть в финальный результат сборки. 
+Первым элементом данного массива должен быть шаблон директорий
 которые содержат файлы с документацией по блокам.
- Значение по умолчанию `['*.sets']`
 
-* `readme` - объект с полями `folder` и `pattern`, по которым сборщик может определить метоположение
- и имя актуального readme файла для библиотеки. При этом поле `pattern` может быть объектом c ключами
- локализации, например: 
-
-```
-pattern: {
-    en: '...',
-    ru: '...'
-}
-```
-
-Это позволяет задавать различные файлы для разных локализаций. 
+Значение по умолчанию `['*.sets']`
+
+##### docs
 
-Кроме того, конфигурация позволяет указывать путь к  произвольному файлу доументации на github.
-Для этого необходимо убрать поле folder а значением поля pattern указать путь (как в браузере)
-к искомому файлу друментации на github, например:
+Объект с полями, которые в свою очередь также являются объектами.
+Позволяет задавать произвольный набор документов которые должны попасть в сборку библиотеки
 
 ```
-readme: {
-    pattern: 'https://github.com/bem/bem-bl/blob/dev/README.ru.md'
-},
+docs: {
+    readme: {
+        folder: '',
+        pattern: 'README.md'
+    },
+    changelog: {
+        folder: 'docs',
+        pattern: {
+            en: 'CHANGELOG.en.md',
+            ru: 'CHANGELOG.en.md'
+        }
+    },
+    migration: {
+        pattern: 'https://github.com/bem/bem-core/tree/v2/MIGRATION.md'
+    }
+    ...
+}    
 ```
+Здесь 'README.md' - загружается из корня проекта. Файлы changelog-ов будут загружены из директории 'docs',
+по маске 'CHANGELOG.en.md' и 'CHANGELOG.ru.md' соответственно. При этом будут выбраны последние версии таких файлов,
+в случае когда в данной директории хранится несколько changelog - файлов и их названия содержат номер версии библиотеки.
+Файл миграции напрямую загружается с гитхаба с помощью github API с указанного адреса.
 
-* `changelog` - аналогично `readme`
-* `migration` - аналогично `readme`
-* `notes` - аналогично `readme`
+Из данного примера видно, что можно задавать разные файлы для различных языков, а также указывать
+произвольный url к файлу как адрес данного файла в браузере.
 
-* `pattern` - объект с полями `data` и `jsdoc` в котором можно указать шаблоны файлов с документацией
-и js документацией к блокам. Значение по умолчанию:
+##### pattern 
+Объект с полями `data` и `jsdoc` в котором можно указать шаблоны файлов с документацией и js документацией к блокам. 
+
+Значение по умолчанию:
 
 ```
 pattern: {
@@ -135,12 +150,21 @@ pattern: {
 }
 ```
 
-* `skip` - массив с именами шагов сборки которые не должны быть выполнены для текущей библиотеки. 
-Допустимые элементы массива: 'npmInstall', 'npmInstallBemSets', 'npmInstallBem', 'npmRunDeps', 'copyBorschik', 'npmRunBuild',
-'copySets', 'collectSets'.
+##### skip 
+Массив с именами шагов сборки которые не должны быть выполнены для текущей библиотеки. 
+
+Допустимые элементы массива: 
+* 'npmInstall' 
+* 'npmInstallBemSets' 
+* 'npmInstallBem' 
+* 'npmRunDeps'
+* 'copyBorschik' 
+* 'npmRunBuild'
+* 'copySets'
+* 'collectSets'.
 
 
-### Запуск
+## Запуск
 
 Запуск выполняется командой `node bin/start.js` с указанием дополнительных опций:
 

diff --git a/src/libs/renderer.js b/src/libs/renderer.js
@@ -0,0 +1,36 @@
+var md = require('marked');
+
+var renderer;
+
+/**
+ * Creates custom renderer for markdown parsing
+ * @returns {marked.Renderer}
+ */
+function createRenderer() {
+    renderer = new md.Renderer();
+
+    /**
+     * Fix marked issue with cyrillic symbols replacing
+     * @param text - {String} test of header
+     * @param level - {Number} index of header
+     * @param raw
+     * @param options - {Object} options
+     * @returns {String} - result header string
+     */
+    renderer.heading = function(text, level, raw, options) {
+        var specials = ['-','[',']','/','{','}','(',')','*','+','?','.','\\','^','$','|','\ ','\'','\"'];
+
+        options = options || {};
+        options.headerPrefix = options.headerPrefix || '';
+
+        return '<h' + level + ' id="' + options.headerPrefix
+            + raw.replace(RegExp('[' + specials.join('\\') + ']', 'g'), '-') + '">'
+            + text + '</h' + level + '>\n';
+    };
+
+    return renderer;
+}
+
+exports.getRenderer = function() {
+    return renderer || createRenderer();
+};
diff --git a/src/libs/util.js b/src/libs/util.js
@@ -8,6 +8,7 @@ var util = require('util'),
     vow = require('vow'),
     md = require('marked'),
 
+    renderer = require('./renderer'),
     logger = require('./logger')(module);
 
 /**
@@ -66,7 +67,8 @@ exports.mdToHtml = function(content) {
     return md(content, {
         gfm: true,
         pedantic: false,
-        sanitize: false
+        sanitize: false,
+        renderer: renderer.getRenderer()
     });
 };