diff --git a/composer.json b/composer.json
index c98684698c1..f6fbb8fa7f6 100644
--- a/composer.json
+++ b/composer.json
@@ -77,7 +77,7 @@
         "lib-pcre": "*",
         "yiisoft/yii2-composer": "*",
         "ezyang/htmlpurifier": "4.6.*",
-        "cebe/markdown": "0.9.*",
+        "cebe/markdown": "~1.0.0",
         "bower-asset/jquery": "2.1.*@stable | 1.11.*@stable",
         "bower-asset/jquery.inputmask": "3.1.*",
         "bower-asset/punycode": "1.3.*",
diff --git a/extensions/apidoc/CHANGELOG.md b/extensions/apidoc/CHANGELOG.md
index 25c9a78cb03..25a0e70aedc 100644
--- a/extensions/apidoc/CHANGELOG.md
+++ b/extensions/apidoc/CHANGELOG.md
@@ -4,8 +4,7 @@ Yii Framework 2 apidoc extension Change Log
 2.0.0 under development
 -----------------------
 
-- no changes in this release.
-
+- Chg: Updated cebe/markdown to 1.0.0 which includes breaking changes in its internal API (cebe)
 
 2.0.0-rc September 27, 2014
 ---------------------------
diff --git a/extensions/apidoc/composer.json b/extensions/apidoc/composer.json
index 5bdced982b9..aea72453def 100644
--- a/extensions/apidoc/composer.json
+++ b/extensions/apidoc/composer.json
@@ -25,7 +25,7 @@
         "phpdocumentor/reflection-docblock": ">2.0.1",
         "nikic/php-parser": "0.9.*",
         "cebe/js-search": "*",
-        "cebe/markdown": "dev-master as 0.9.0",
+        "cebe/markdown": "~1.0.0",
         "cebe/markdown-latex": "*"
     },
     "autoload": {
diff --git a/extensions/apidoc/helpers/ApiMarkdown.php b/extensions/apidoc/helpers/ApiMarkdown.php
index dde0b8334ad..9a58bacf3f7 100644
--- a/extensions/apidoc/helpers/ApiMarkdown.php
+++ b/extensions/apidoc/helpers/ApiMarkdown.php
@@ -40,7 +40,7 @@ protected function renderCode($block)
         if (isset($block['language'])) {
             $class = isset($block['language']) ? ' class="language-' . $block['language'] . '"' : '';
 
-            return "<pre><code$class>" . $this->highlight(implode("\n", $block['content']) . "\n", $block['language']) . '</code></pre>';
+            return "<pre><code$class>" . $this->highlight($block['content'] . "\n", $block['language']) . '</code></pre>';
         } else {
             return parent::renderCode($block);
         }
diff --git a/extensions/apidoc/helpers/ApiMarkdownTrait.php b/extensions/apidoc/helpers/ApiMarkdownTrait.php
index 39e7b47b34c..f7ac40e0528 100644
--- a/extensions/apidoc/helpers/ApiMarkdownTrait.php
+++ b/extensions/apidoc/helpers/ApiMarkdownTrait.php
@@ -18,6 +18,10 @@
  */
 trait ApiMarkdownTrait
 {
+    /**
+     * @marker [[
+     * TODO adjust implementation
+     */
     protected function parseApiLinks($text)
     {
         $context = $this->renderingContext;
diff --git a/extensions/apidoc/helpers/IndexFileAnalyzer.php b/extensions/apidoc/helpers/IndexFileAnalyzer.php
index bfa6e619cbd..0fe161fb260 100644
--- a/extensions/apidoc/helpers/IndexFileAnalyzer.php
+++ b/extensions/apidoc/helpers/IndexFileAnalyzer.php
@@ -28,7 +28,7 @@ public function analyze($text)
     protected function renderHeadline($block)
     {
         if ($this->_chapter === 0) {
-            $this->title = $block['content'];
+            $this->title = $block['content']; // TODO adjust implementation
             $this->introduction = '';
             $this->_chapter++;
         } else {
diff --git a/framework/CHANGELOG.md b/framework/CHANGELOG.md
index 9b3b1223dbf..eb89fd7fb8b 100644
--- a/framework/CHANGELOG.md
+++ b/framework/CHANGELOG.md
@@ -21,6 +21,7 @@ Yii Framework 2 Change Log
 - Enh #5316: Added `startsWith()` and `endsWith()` to `yii\helpers\StringHelper`. Methods are binary-safe, multibyte-safe and optionally case-insensitive (armab)
 - Enh #5467: Added ability to pass HTML tag options to `asEmail()`, `asImage()` and `asUrl()` methods of `yii\i18n\Formatter` (alxkolm, samdark) 
 - Chg #2037: Dropped the support for using `yii\base\Module` as concrete module classes (qiangxue)
+- Chg: Updated cebe/markdown to 1.0.0 which includes breaking changes in its internal API (cebe)
 
 
 2.0.0-rc September 27, 2014
diff --git a/framework/UPGRADE.md b/framework/UPGRADE.md
index 115cefba3ff..37d6fda0b21 100644
--- a/framework/UPGRADE.md
+++ b/framework/UPGRADE.md
@@ -28,6 +28,9 @@ Upgrade from Yii 2.0 RC
 * If you've used `asImage` formatter i.e. `Yii::$app->formatter->asImage($value, $alt);` you should change it
   to `Yii::$app->formatter->asImage($value, ['alt' => $alt]);`.
 
+* Yii now requires `cebe/markdown` 1.0.0 or higher, which includes breaking changes in its internal API. If you extend the markdown class
+  you need to update your implementation. See <https://github.com/cebe/markdown/releases/tag/1.0.0-rc> for details.
+  If you just used the markdown helper class there is no need to change anything.
 
 Upgrade from Yii 2.0 Beta
 -------------------------
diff --git a/framework/composer.json b/framework/composer.json
index d6cc082c984..f257f30618c 100644
--- a/framework/composer.json
+++ b/framework/composer.json
@@ -57,7 +57,7 @@
         "lib-pcre": "*",
         "yiisoft/yii2-composer": "*",
         "ezyang/htmlpurifier": "4.6.*",
-        "cebe/markdown": "0.9.*",
+        "cebe/markdown": "~1.0.0",
         "bower-asset/jquery": "2.1.*@stable | 1.11.*@stable",
         "bower-asset/jquery.inputmask": "3.1.*",
         "bower-asset/punycode": "1.3.*",