Bump version to 4.0.0-alpha.6 🚀

gitbook: Remove "title" and "description" from Readme (#1748 )
Bump version to 4.0.0-alpha.5 🚀
2026-09-16 07:35:16 +00:00 · 2017-03-16 15:12:46 +01:00 · 2017-03-14 14:08:55 +01:00 · 2017-03-09 11:18:00 +01:00 · 2017-03-09 11:06:23 +01:00 · 2017-02-15 18:12:59 +01:00
24 changed files with 246 additions and 133 deletions
@@ -65,7 +65,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Headings are no longer annotated with glossary terms
 - Themes are now published as a plugin, with ability to extend it from the book source
 - `links.sidebar` configuration is no longer supported, use summary sections instead
- `pdf.headerTemplate` and `pdf.footerTemplate` have been replaced by a template in theme/book: `_layout/ebook/pdf_header.html` and `_layout/ebook/pdf_footer.html`
+- `pdf.headerTemplate` and `pdf.footerTemplate` have been replaced by a template in theme/book: `_layouts/ebook/pdf_header.html` and `_layouts/ebook/pdf_footer.html`
 - Markdown parser is now using CommonMark
 - Root folder for the book can be specified in the `"root"` property of the `book.json` file
 - Multi-lingual books share assets folder
@@ -68,7 +68,7 @@ Parts are just groups of chapters and do not have dedicated pages, but according

 #### Markdown syntax

-Most of the files for GitBook use the Markdown syntax by default. GitBook infers your pages's structure from it. The syntax used is similar to the [GitHub Flavored Markdown syntax](https://guides.github.com/features/mastering-markdown/). One can also opt for the [AsciiDoc syntax](asciidoc.md).
+Most of the files for GitBook use the Markdown syntax by default. GitBook infers your pages's structure from it. The syntax used is similar to the [GitHub Flavored Markdown syntax](https://guides.github.com/features/mastering-markdown/). One can also opt for the [AsciiDoc syntax](syntax/asciidoc.md).

 ##### Example of a chapter file

@@ -1,4 +1,4 @@
 {
  "lerna": "2.0.0-beta.31",
-  "version": "4.0.0-alpha.4"
+  "version": "4.0.0-alpha.6"
 }
@@ -1,6 +1,6 @@
 {
  "name": "gitbook-core",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "description": "Core for GitBook plugins API",
  "main": "./lib/index.js",
  "dependencies": {
@@ -3,13 +3,13 @@
  "description": "Button to copy code blocks",
  "main": "index.js",
  "browser": "./_assets/plugin.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "dependencies": {
    "copy-to-clipboard": "^3.0.5",
-    "gitbook-core": "^4.0.0-alpha.4"
+    "gitbook-core": "^4.0.0-alpha.6"
  },
  "devDependencies": {
-    "gitbook-plugin": "^4.0.0-alpha.4"
+    "gitbook-plugin": "^4.0.0-alpha.6"
  },
  "engines": {
    "gitbook": ">=3.0.0"
@@ -3,13 +3,13 @@
  "description": "Automatically add anchors to headings",
  "main": "index.js",
  "browser": "./_assets/plugin.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "dependencies": {
    "classnames": "^2.2.5",
-    "gitbook-core": "^4.0.0-alpha.4"
+    "gitbook-core": "^4.0.0-alpha.6"
  },
  "devDependencies": {
-    "gitbook-plugin": "^4.0.0-alpha.4"
+    "gitbook-plugin": "^4.0.0-alpha.6"
  },
  "engines": {
    "gitbook": ">=3.0.0"
@@ -3,13 +3,13 @@
  "description": "Syntax highlighter for Gitbook",
  "main": "index.js",
  "browser": "./_assets/plugin.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "dependencies": {
-    "gitbook-core": "^4.0.0-alpha.4",
+    "gitbook-core": "^4.0.0-alpha.6",
    "highlight.js": "9.7.0"
  },
  "devDependencies": {
-    "gitbook-plugin": "^4.0.0-alpha.4"
+    "gitbook-plugin": "^4.0.0-alpha.6"
  },
  "engines": {
    "gitbook": ">=3.0.0"
@@ -3,13 +3,13 @@
  "description": "Defines four types of styled hint blocks: info, danger, tip, working.",
  "main": "index.js",
  "browser": "./_assets/plugin.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "dependencies": {
    "classnames": "^2.2.5",
-    "gitbook-core": "^4.0.0-alpha.4"
+    "gitbook-core": "^4.0.0-alpha.6"
  },
  "devDependencies": {
-    "gitbook-plugin": "^4.0.0-alpha.4"
+    "gitbook-plugin": "^4.0.0-alpha.6"
  },
  "engines": {
    "gitbook": ">=4.0.0"
@@ -3,15 +3,15 @@
  "description": "Live reloading for your gitbook",
  "main": "index.js",
  "browser": "./_assets/plugin.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "engines": {
    "gitbook": "*"
  },
  "dependencies": {
-    "gitbook-core": "^4.0.0-alpha.4"
+    "gitbook-core": "^4.0.0-alpha.6"
  },
  "devDependencies": {
-    "gitbook-plugin": "^4.0.0-alpha.4"
+    "gitbook-plugin": "^4.0.0-alpha.6"
  },
  "scripts": {
    "build-js": "gitbook-plugin build ./src/index.js ./_assets/plugin.js",
@@ -3,14 +3,14 @@
  "description": "Static and local index for search in GitBook",
  "main": "index.js",
  "browser": "./_assets/theme.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "dependencies": {
-    "gitbook-core": "^4.0.0-alpha.4",
+    "gitbook-core": "^4.0.0-alpha.6",
    "html-entities": "1.2.0",
    "lunr": "0.5.12"
  },
  "devDependencies": {
-    "gitbook-plugin": "^4.0.0-alpha.4"
+    "gitbook-plugin": "^4.0.0-alpha.6"
  },
  "engines": {
    "gitbook": ">=3.0.0"
@@ -3,13 +3,13 @@
  "description": "Search integration in GitBook",
  "main": "index.js",
  "browser": "./_assets/theme.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "dependencies": {
-    "gitbook-core": "^4.0.0-alpha.4",
+    "gitbook-core": "^4.0.0-alpha.6",
    "react": "^15.4.1"
  },
  "devDependencies": {
-    "gitbook-plugin": "^4.0.0-alpha.4",
+    "gitbook-plugin": "^4.0.0-alpha.6",
    "react-highlighter": "^0.3.3"
  },
  "engines": {
@@ -3,7 +3,7 @@
  "description": "Sharing buttons in the toolbar",
  "main": "index.js",
  "browser": "./_assets/plugin.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "gitbook": {
    "properties": {
      "facebook": {
@@ -53,10 +53,10 @@
    }
  },
  "dependencies": {
-    "gitbook-core": "^4.0.0-alpha.4"
+    "gitbook-core": "^4.0.0-alpha.6"
  },
  "devDependencies": {
-    "gitbook-plugin": "^4.0.0-alpha.4"
+    "gitbook-plugin": "^4.0.0-alpha.6"
  },
  "engines": {
    "gitbook": ">=3.0.0"
@@ -3,19 +3,19 @@
  "description": "Default theme for GitBook",
  "main": "./index.js",
  "browser": "./_assets/theme.js",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "engines": {
    "gitbook": ">=3.0.0"
  },
  "dependencies": {
    "debounce": "^1.0.0",
-    "gitbook-core": "^4.0.0-alpha.4"
+    "gitbook-core": "^4.0.0-alpha.6"
  },
  "devDependencies": {
    "classnames": "^2.2.5",
    "font-awesome": "^4.6.3",
    "gitbook-markdown-css": "^1.0.1",
-    "gitbook-plugin": "^4.0.0-alpha.4",
+    "gitbook-plugin": "^4.0.0-alpha.6",
    "less": "^2.7.1",
    "less-plugin-clean-css": "^1.5.1",
    "preboot": "git+https://github.com/mdo/preboot.git#4aab4edd85f076d50609cbe28e4fe66cc0771701"
@@ -1,6 +1,6 @@
 {
  "name": "gitbook-plugin",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "description": "CLI for compiling and testing plugins",
  "main": "./lib/index.js",
  "dependencies": {
@@ -1,6 +1,6 @@
 {
  "name": "gitbook",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
  "homepage": "https://www.gitbook.com",
  "description": "Library and cmd utility to generate GitBooks",
  "main": "lib/index.js",
@@ -22,16 +22,16 @@
    "extend": "^3.0.0",
    "fresh-require": "1.0.3",
    "front-matter": "^2.1.0",
-    "gitbook-core": "^4.0.0-alpha.4",
-    "gitbook-plugin-copy-code": "^4.0.0-alpha.4",
-    "gitbook-plugin-headings": "^4.0.0-alpha.4",
-    "gitbook-plugin-highlight": "^4.0.0-alpha.4",
-    "gitbook-plugin-hints": "^4.0.0-alpha.4",
-    "gitbook-plugin-livereload": "^4.0.0-alpha.4",
-    "gitbook-plugin-lunr": "^4.0.0-alpha.4",
-    "gitbook-plugin-search": "^4.0.0-alpha.4",
-    "gitbook-plugin-sharing": "^4.0.0-alpha.4",
-    "gitbook-plugin-theme-default": "^4.0.0-alpha.4",
+    "gitbook-core": "^4.0.0-alpha.6",
+    "gitbook-plugin-copy-code": "^4.0.0-alpha.6",
+    "gitbook-plugin-headings": "^4.0.0-alpha.6",
+    "gitbook-plugin-highlight": "^4.0.0-alpha.6",
+    "gitbook-plugin-hints": "^4.0.0-alpha.6",
+    "gitbook-plugin-livereload": "^4.0.0-alpha.6",
+    "gitbook-plugin-lunr": "^4.0.0-alpha.6",
+    "gitbook-plugin-search": "^4.0.0-alpha.6",
+    "gitbook-plugin-sharing": "^4.0.0-alpha.6",
+    "gitbook-plugin-theme-default": "^4.0.0-alpha.6",
    "github-slugid": "1.0.1",
    "graceful-fs": "4.1.4",
    "i18n-t": "1.0.1",
@@ -43,7 +43,7 @@
    "json-schema-defaults": "0.1.1",
    "jsonschema": "1.1.0",
    "juice": "2.0.0",
-    "markup-it": "^3.2.2",
+    "markup-it": "^3.4.0",
    "mkdirp": "0.5.1",
    "moment": "2.13.0",
    "npm": "3.10.9",
@@ -2,9 +2,7 @@ const { Record } = require('immutable');
 const File = require('./file');

 const DEFAULTS = {
-    file:        new File(),
-    title:       String(),
-    description: String()
+    file:        new File()
 };

 class Readme extends Record(DEFAULTS) {
@@ -12,14 +10,6 @@ class Readme extends Record(DEFAULTS) {
        return this.get('file');
    }

-    getTitle() {
-        return this.get('title');
-    }
-
-    getDescription() {
-        return this.get('description');
-    }
-
    /**
     * Set file linked to the readme.
     * @param  {File} file
@@ -32,7 +22,6 @@ class Readme extends Record(DEFAULTS) {
    /**
     * Create a new readme
     *
-     * @param {File} file
     * @param {Object} def
     * @return {Readme}
     */
@@ -40,8 +29,7 @@ class Readme extends Record(DEFAULTS) {
        def = def || {};

        return new Readme({
-            title: def.title || '',
-            description: def.description || ''
+            file: def.file || ''
        });
    }
 }
@@ -21,5 +21,11 @@ nodes:
          - kind: block
            type: unstyled
            nodes:
-              - kind: text
-                text: ''
+              - kind: inline
+                type: link
+                data:
+                  href: 'art1.md'
+                nodes:
+                  - kind: text
+                    text: '' # No title so ignored
+
@@ -0,0 +1,115 @@
+nodes:
+  - kind: block
+    type: header_one
+    nodes:
+      - kind: text
+        text: Summary
+  - kind: block
+    type: unordered_list
+    nodes:
+      - kind: block
+        type: list_item
+        nodes:
+          - kind: block
+            type: unstyled
+            nodes:
+              - kind: text
+                text: 'ignored text'
+              - kind: inline
+                type: link
+                data:
+                  href: 'art1.md'
+                nodes:
+                  - kind: text
+                    text: 'Article 1'
+              - kind: text
+                text: ''
+
+      - kind: block
+        type: list_item
+        nodes:
+          - kind: block
+            type: paragraph
+            nodes:
+              - kind: text
+                text: 'Article 2'
+          - kind: block
+            type: paragraph
+            nodes:
+              - kind: text
+                text: 'Ignored'
+
+      - kind: block
+        type: list_item
+        nodes:
+          - kind: block
+            type: paragraph
+            nodes:
+              - kind: text
+                text: 'First paragraph. There is a link further, so should be ignored'
+
+          # Sublist, that is not after a link. Should be ignored
+          - kind: block
+            type: unordered_list
+            nodes:
+              - kind: block
+                type: list_item
+                nodes:
+                  - kind: block
+                    type: unstyled
+                    nodes:
+                      - kind: inline
+                        type: link
+                        data:
+                          href: 'ignored.md'
+                        nodes:
+                          - kind: text
+                            text: 'Ignored'
+
+          - kind: block
+            type: paragraph
+            nodes:
+              - kind: inline
+                type: link
+                data:
+                  href: 'art3.md'
+                nodes:
+                  - kind: text
+                    text: 'Article 3'
+
+          # First sublist that is after the link. Parsed as subarticles
+          - kind: block
+            type: unordered_list
+            nodes:
+              - kind: block
+                type: list_item
+                nodes:
+                  - kind: block
+                    type: unstyled
+                    nodes:
+                      - kind: inline
+                        type: link
+                        data:
+                          href: 'art2.1.md'
+                        nodes:
+                          - kind: text
+                            text: 'Article 2.1'
+
+          # Ignored because we already parsed the previous list
+          - kind: block
+            type: unordered_list
+            nodes:
+              - kind: block
+                type: list_item
+                nodes:
+                  - kind: block
+                    type: unstyled
+                    nodes:
+                      - kind: inline
+                        type: link
+                        data:
+                          href: 'ignored'
+                        nodes:
+                          - kind: text
+                            text: 'ignored'
+
@@ -16,8 +16,6 @@ describe('parseReadme', () => {
            const file = readme.getFile();

            expect(file.exists()).toBeTruthy();
-            expect(readme.title).toBe('Hello');
-            expect(readme.description).toBe('And here is the description.');
        });
    });

@@ -1,24 +0,0 @@
-const expect = require('expect');
-const readDocument = require('./utils/readDocument');
-const readmeFromDocument = require('../readmeFromDocument');
-
-function readReadme(filename) {
-    const document = readDocument(filename);
-    return readmeFromDocument(document);
-}
-
-describe('readmeFromDocument', () => {
-
-    it('should parse only title', () => {
-        const readme = readReadme('readme/only-title.yaml');
-        expect(readme.title).toBe('Hello World');
-        expect(readme.description).toBe('');
-    });
-
-    it('should parse title and description', () => {
-        const readme = readReadme('readme/normal.yaml');
-        expect(readme.title).toBe('Hello World');
-        expect(readme.description).toBe('This is a description');
-    });
-
-});
@@ -92,22 +92,13 @@ describe('summaryFromDocument', () => {
        ]);
    });

-    it('should parse empty items', () => {
+    it('should ignore empty items', () => {
        const summary = readSummary('summary/empty-items.yaml');

        expectParts(summary, [
            {
                title: '',
-                articles: [
-                    {
-                        title: '',
-                        ref: ''
-                    },
-                    {
-                        title: '',
-                        ref: ''
-                    }
-                ]
+                articles: []
            }
        ]);
    });
@@ -210,4 +201,36 @@ describe('summaryFromDocument', () => {
        expectParts(summary, [
        ]);
    });
+
+    it('should be flexible', () => {
+        const summary = readSummary('summary/flexible.yaml');
+
+        expectParts(summary, [
+            {
+                title: '',
+                articles: [
+                    {
+                        title: 'Article 1',
+                        ref: 'art1.md'
+                    },
+                    {
+                        title: 'Article 2',
+                        articles: []
+                    },
+                    {
+                        title: 'Article 3',
+                        ref: 'art3.md',
+                        articles: [
+                            {
+                                title: 'Article 2.1',
+                                ref: 'art2.1.md',
+                                articles: []
+                            }
+                        ]
+                    }
+                ]
+            }
+        ]);
+    });
+
 });
@@ -1,5 +1,5 @@
 const lookupStructureFile = require('./lookupStructureFile');
-const readmeFromDocument = require('./readmeFromDocument');
+const Readme = require('../models/readme');
 const error = require('../utils/error');

 /**
@@ -10,7 +10,6 @@ const error = require('../utils/error');
 */
 function parseReadme(book) {
    const { logger } = book;
-    const fs = book.getContentFS();

    return lookupStructureFile(book, 'readme')
    .then((file) => {
@@ -19,12 +18,8 @@ function parseReadme(book) {
        }

        logger.debug.ln(`readme found at ${file.path}`);
-        return file.parse(fs)
-        .then((document) => {
-            let readme = readmeFromDocument(document);
-            readme = readme.setFile(file);
-            return book.set('readme', readme);
-        });
+
+        return book.set('readme', Readme.create({ file }));
    });
 }

@@ -1,21 +0,0 @@
-const { BLOCKS } = require('markup-it');
-const Readme = require('../models/readme');
-
-/**
- * Parse a readme from a document.
- * @param  {Document} document
- * @return {Readme} readme
- */
-function readmeFromDocument(document) {
-    const { nodes } = document;
-
-    const first = nodes.first();
-    const second = nodes.get(1);
-
-    return Readme.create({
-        title: first && first.type == BLOCKS.HEADING_1 ? first.text : '',
-        description: second && second.type == BLOCKS.PARAGRAPH ? second.text : ''
-    });
-}
-
-module.exports = readmeFromDocument;
@@ -9,17 +9,48 @@ const isLink = node => node.type === INLINES.LINK;
 /**
 * Create a summary article from a list item.
 * @param  {Block} item
- * @return {SummaryArticleLike} article
+ * @return {SummaryArticleLike | Null} article
 */
 function createArticleFromItem(item) {
    const { nodes } = item;

-    const titleParent = nodes.first();
-    const list = nodes.skip(1).find(isList);
+    // Find the link that represents the article's title
+    const linkParent = nodes
+        .filterNot(isList)
+        .find(node => node.findDescendant(isLink));
+
+    // Or find text that could act as title
+    const textParent = nodes.filterNot(node => isList(node) || node.isEmpty).first();
+
+    let title, ref, parent;
+    if (linkParent) {
+        const link = linkParent.findDescendant(isLink);
+
+        if (!link.isEmpty) {
+            parent = linkParent;
+            title = link.text;
+            ref = link.data.get('href');
+        }
+    }
+
+    if (!parent) {
+        // Could not find a proper link
+
+        if (textParent) {
+            parent = textParent;
+            title = textParent.text;
+            ref = null;
+        } else {
+            // This item has no proper title or link
+            return null;
+        }
+    }
+
+    const list = nodes
+        // Skip until after the article's title or link
+        .skipUntil(node => node === parent).skip(1)
+        .find(isList);
    const articles = list ? listArticles(list) : [];
-    const title = titleParent.text;
-    const link = titleParent.findDescendant(isLink);
-    const ref = link ? link.data.get('href') : null;

    return {
        title,
@@ -35,7 +66,9 @@ function createArticleFromItem(item) {
 */
 function listArticles(list) {
    const { nodes } = list;
-    return nodes.map(item => createArticleFromItem(item));
+    return nodes
+        .map(item => createArticleFromItem(item))
+        .filter(article => Boolean(article));
 }

 /**
Author	SHA1	Message	Date
Samy Pessé	ef84a34fcd	Bump version to 4.0.0-alpha.6 🚀	2017-03-16 15:12:46 +01:00
Nicolas Gaborit	5df4c358a4	gitbook: Remove "title" and "description" from Readme (#1748 )	2017-03-14 14:08:55 +01:00
Samy Pessé	caa8c52222	Bump version to 4.0.0-alpha.5 🚀	2017-03-09 11:18:00 +01:00
Nicolas Gaborit	c3e243c775	Ignore empty articles, and be more flexible in parsing articles (#1741 ) * Ignore empty articles, and be more flexible in parsing articles * gitbook: Update markup-it^3.4.0	2017-03-09 11:06:23 +01:00
YuLun Shih	4e3e3e515d	fix typo: _layout to _layouts (#1714 )	2017-02-15 18:12:59 +01:00
Piotr Kuczynski	2661a58776	Fixed link to AsciiDoc (#1691 )	2017-02-02 17:34:14 +01:00