From b3670ece0ec72610ad31283c6b6b2c7f556eeba1 Mon Sep 17 00:00:00 2001 From: Jonas Berlin Date: Mon, 17 Feb 2020 22:59:37 +0200 Subject: [PATCH 1/8] Add "Suggest an edit" link next to "Git repository" Includes new configuration option `git-repository-edit-baseurl` for supporting non-GitHub repository layouts. --- guide/src/format/config.md | 6 ++++++ src/config.rs | 5 +++++ src/renderer/html_handlebars/hbs_renderer.rs | 10 ++++++++++ src/theme/index.hbs | 6 ++++++ 4 files changed, 27 insertions(+) diff --git a/guide/src/format/config.md b/guide/src/format/config.md index d9c77e66..f1f65128 100644 --- a/guide/src/format/config.md +++ b/guide/src/format/config.md @@ -201,6 +201,12 @@ The following configuration options are available: an icon link will be output in the menu bar of the book. - **git-repository-icon:** The FontAwesome icon class to use for the git repository link. Defaults to `fa-github`. +- **git-repository-edit-baseurl:** The base url for suggesting an edit + to individual pages/chapters of the book. If **git-repository-url** is defined, + defaults to **git-repository-url**/blob/master which works for e.g. GitHub. + The page source path is appended to this url, e.g. `/src/SUMMARY.md`. So when + this or **git-repository-url** is configured an icon link will be output in + the menu bar of the book. - **redirect:** A subtable used for generating redirects when a page is moved. The table contains key-value pairs where the key is where the redirect file needs to be created, as an absolute path from the build directory, (e.g. diff --git a/src/config.rs b/src/config.rs index be7dae62..1191542b 100644 --- a/src/config.rs +++ b/src/config.rs @@ -522,6 +522,11 @@ pub struct HtmlConfig { /// /// [custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site pub cname: Option, + /// Git repository file edit baseurl, below which e.g. src/SUMMARY.md can + /// be viewed/edited + /// Defaults to git_repository_url + `/blob/master` if `None` and + /// git_repository_url is not `None` - works for e.g. GitHub master branch + pub git_repository_edit_baseurl: Option, /// This is used as a bit of a workaround for the `mdbook serve` command. /// Basically, because you set the websocket port from the command line, the /// `mdbook serve` command needs a way to let the HTML renderer know where diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index 254f189f..ad0a271e 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -680,6 +680,16 @@ fn make_data( if let Some(ref git_repository_url) = html_config.git_repository_url { data.insert("git_repository_url".to_owned(), json!(git_repository_url)); + let defaultEditBaseUrl = git_repository_url.to_owned() + "/blob/master"; + let git_repository_edit_baseurl = match html_config.git_repository_edit_baseurl { + Some(ref git_repository_edit_baseurl) => git_repository_edit_baseurl, + None => &defaultEditBaseUrl, + }; + data.insert("git_repository_edit_baseurl".to_owned(), json!(git_repository_edit_baseurl)); + } else { + if let Some(ref git_repository_edit_baseurl) = html_config.git_repository_edit_baseurl { + data.insert("git_repository_edit_baseurl".to_owned(), json!(git_repository_edit_baseurl)); + } } let git_repository_icon = match html_config.git_repository_icon { diff --git a/src/theme/index.hbs b/src/theme/index.hbs index e9e6cff8..a1cbe6e4 100644 --- a/src/theme/index.hbs +++ b/src/theme/index.hbs @@ -148,6 +148,12 @@ {{/if}} + {{#if git_repository_edit_baseurl}} + + + + {{/if}} + From 2b738d4425cf93ae5664cc2dbf42c7ad1e36fe5e Mon Sep 17 00:00:00 2001 From: Jonas Berlin Date: Mon, 17 Feb 2020 23:05:33 +0200 Subject: [PATCH 2/8] [ReviewFix] Fix variable naming --- src/renderer/html_handlebars/hbs_renderer.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index ad0a271e..c91ab0cf 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -680,10 +680,10 @@ fn make_data( if let Some(ref git_repository_url) = html_config.git_repository_url { data.insert("git_repository_url".to_owned(), json!(git_repository_url)); - let defaultEditBaseUrl = git_repository_url.to_owned() + "/blob/master"; + let default_edit_baseurl = git_repository_url.to_owned() + "/blob/master"; let git_repository_edit_baseurl = match html_config.git_repository_edit_baseurl { Some(ref git_repository_edit_baseurl) => git_repository_edit_baseurl, - None => &defaultEditBaseUrl, + None => &default_edit_baseurl, }; data.insert("git_repository_edit_baseurl".to_owned(), json!(git_repository_edit_baseurl)); } else { From dcc642e66d0e7e96360d5c08a36ff7fb7edfdc0d Mon Sep 17 00:00:00 2001 From: Jonas Berlin Date: Mon, 17 Feb 2020 23:09:59 +0200 Subject: [PATCH 3/8] [ReviewFix] cargo fmt --- src/renderer/html_handlebars/hbs_renderer.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index c91ab0cf..b0903e7b 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -685,10 +685,16 @@ fn make_data( Some(ref git_repository_edit_baseurl) => git_repository_edit_baseurl, None => &default_edit_baseurl, }; - data.insert("git_repository_edit_baseurl".to_owned(), json!(git_repository_edit_baseurl)); + data.insert( + "git_repository_edit_baseurl".to_owned(), + json!(git_repository_edit_baseurl), + ); } else { if let Some(ref git_repository_edit_baseurl) = html_config.git_repository_edit_baseurl { - data.insert("git_repository_edit_baseurl".to_owned(), json!(git_repository_edit_baseurl)); + data.insert( + "git_repository_edit_baseurl".to_owned(), + json!(git_repository_edit_baseurl), + ); } } From bbf54d7459889697c74101bd0cd4f45f6c0d2ca0 Mon Sep 17 00:00:00 2001 From: Jonas Berlin Date: Tue, 18 Feb 2020 00:41:03 +0200 Subject: [PATCH 4/8] [ReviewFix] Replace edit baseurl with template and make visibility independent of git_repository_url. --- guide/src/format/config.md | 15 +++++++----- src/config.rs | 10 ++++---- src/renderer/html_handlebars/hbs_renderer.rs | 25 +++++++------------- src/theme/index.hbs | 4 ++-- 4 files changed, 25 insertions(+), 29 deletions(-) diff --git a/guide/src/format/config.md b/guide/src/format/config.md index f1f65128..7b19654b 100644 --- a/guide/src/format/config.md +++ b/guide/src/format/config.md @@ -201,12 +201,15 @@ The following configuration options are available: an icon link will be output in the menu bar of the book. - **git-repository-icon:** The FontAwesome icon class to use for the git repository link. Defaults to `fa-github`. -- **git-repository-edit-baseurl:** The base url for suggesting an edit - to individual pages/chapters of the book. If **git-repository-url** is defined, - defaults to **git-repository-url**/blob/master which works for e.g. GitHub. - The page source path is appended to this url, e.g. `/src/SUMMARY.md`. So when - this or **git-repository-url** is configured an icon link will be output in - the menu bar of the book. +- **git-repository-edit-url-template:** Git repository file edit url + template, when provided shows an "Suggest an edit" button for + directly jumping to editing the currently viewed page in the git + repository. For e.g. GitHub projects set this to + `https://github.com///edit/master/{path}` or for + Bitbucket projects set it to + `https://bitbucket.org///src/master/{path}?mode=edit` + where {path} will be replaced with the full path of the file in the + repository. - **redirect:** A subtable used for generating redirects when a page is moved. The table contains key-value pairs where the key is where the redirect file needs to be created, as an absolute path from the build directory, (e.g. diff --git a/src/config.rs b/src/config.rs index 1191542b..061a2499 100644 --- a/src/config.rs +++ b/src/config.rs @@ -522,11 +522,11 @@ pub struct HtmlConfig { /// /// [custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site pub cname: Option, - /// Git repository file edit baseurl, below which e.g. src/SUMMARY.md can - /// be viewed/edited - /// Defaults to git_repository_url + `/blob/master` if `None` and - /// git_repository_url is not `None` - works for e.g. GitHub master branch - pub git_repository_edit_baseurl: Option, + /// Git repository file edit url template, when set shows an + /// "Suggest an edit" button for directly jumping to editing the + /// currently viewed page in the git repository. Contains {path} + /// that is replaced with chapter source file path + pub git_repository_edit_url_template: Option, /// This is used as a bit of a workaround for the `mdbook serve` command. /// Basically, because you set the websocket port from the command line, the /// `mdbook serve` command needs a way to let the HTML renderer know where diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index b0903e7b..9279d5d3 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -37,6 +37,15 @@ impl HtmlHandlebars { _ => return Ok(()), }; + if let Some(ref git_repository_edit_url_template) = + ctx.html_config.git_repository_edit_url_template + { + let full_path = "src/".to_owned() + path.to_str().unwrap(); + let edit_url = git_repository_edit_url_template.replace("{path}", &full_path); + ctx.data + .insert("git_repository_edit_url".to_owned(), json!(edit_url)); + } + let content = ch.content.clone(); let content = utils::render_markdown(&content, ctx.html_config.curly_quotes); @@ -680,22 +689,6 @@ fn make_data( if let Some(ref git_repository_url) = html_config.git_repository_url { data.insert("git_repository_url".to_owned(), json!(git_repository_url)); - let default_edit_baseurl = git_repository_url.to_owned() + "/blob/master"; - let git_repository_edit_baseurl = match html_config.git_repository_edit_baseurl { - Some(ref git_repository_edit_baseurl) => git_repository_edit_baseurl, - None => &default_edit_baseurl, - }; - data.insert( - "git_repository_edit_baseurl".to_owned(), - json!(git_repository_edit_baseurl), - ); - } else { - if let Some(ref git_repository_edit_baseurl) = html_config.git_repository_edit_baseurl { - data.insert( - "git_repository_edit_baseurl".to_owned(), - json!(git_repository_edit_baseurl), - ); - } } let git_repository_icon = match html_config.git_repository_icon { diff --git a/src/theme/index.hbs b/src/theme/index.hbs index a1cbe6e4..669690b4 100644 --- a/src/theme/index.hbs +++ b/src/theme/index.hbs @@ -148,8 +148,8 @@ {{/if}} - {{#if git_repository_edit_baseurl}} - + {{#if git_repository_edit_url}} + {{/if}} From 7aff98a8596bd7d52a54f7729f210b53566b9f8c Mon Sep 17 00:00:00 2001 From: Flavio Castelli Date: Mon, 19 Apr 2021 18:58:15 +0200 Subject: [PATCH 5/8] Fix generation of edit links The `IndexPreprocessor` rewrites the path for files named `README.md` to be `index.md`. This breaks the edit link in some circumstances. To address this issues, the `Chapter` struct has now a new attribute called `source_path`. This is initialized with the same value as `path`, but is never ever changed. Finally, the edit link is built by using the `source_path` rather than the `path`. --- src/book/book.rs | 14 ++++++++++++-- src/config.rs | 1 + src/renderer/html_handlebars/hbs_renderer.rs | 7 ++++++- 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/src/book/book.rs b/src/book/book.rs index 95382960..048aef28 100644 --- a/src/book/book.rs +++ b/src/book/book.rs @@ -160,6 +160,8 @@ pub struct Chapter { pub sub_items: Vec, /// The chapter's location, relative to the `SUMMARY.md` file. pub path: Option, + /// The chapter's source file, relative to the `SUMMARY.md` file. + pub source_path: Option, /// An ordered list of the names of each chapter above this one in the hierarchy. pub parent_names: Vec, } @@ -169,13 +171,15 @@ impl Chapter { pub fn new>( name: &str, content: String, - path: P, + p: P, parent_names: Vec, ) -> Chapter { + let path: PathBuf = p.into(); Chapter { name: name.to_string(), content, - path: Some(path.into()), + path: Some(path.clone()), + source_path: Some(path), parent_names, ..Default::default() } @@ -188,6 +192,7 @@ impl Chapter { name: name.to_string(), content: String::new(), path: None, + source_path: None, parent_names, ..Default::default() } @@ -438,6 +443,7 @@ And here is some \ content: String::from("Hello World!"), number: Some(SectionNumber(vec![1, 2])), path: Some(PathBuf::from("second.md")), + source_path: Some(PathBuf::from("second.md")), parent_names: vec![String::from("Chapter 1")], sub_items: Vec::new(), }; @@ -446,6 +452,7 @@ And here is some \ content: String::from(DUMMY_SRC), number: None, path: Some(PathBuf::from("chapter_1.md")), + source_path: Some(PathBuf::from("chapter_1.md")), parent_names: Vec::new(), sub_items: vec![ BookItem::Chapter(nested.clone()), @@ -470,6 +477,7 @@ And here is some \ name: String::from("Chapter 1"), content: String::from(DUMMY_SRC), path: Some(PathBuf::from("chapter_1.md")), + source_path: Some(PathBuf::from("chapter_1.md")), ..Default::default() })], ..Default::default() @@ -510,6 +518,7 @@ And here is some \ content: String::from(DUMMY_SRC), number: None, path: Some(PathBuf::from("Chapter_1/index.md")), + source_path: Some(PathBuf::from("Chapter_1/index.md")), parent_names: Vec::new(), sub_items: vec![ BookItem::Chapter(Chapter::new( @@ -562,6 +571,7 @@ And here is some \ content: String::from(DUMMY_SRC), number: None, path: Some(PathBuf::from("Chapter_1/index.md")), + source_path: Some(PathBuf::from("Chapter_1/index.md")), parent_names: Vec::new(), sub_items: vec![ BookItem::Chapter(Chapter::new( diff --git a/src/config.rs b/src/config.rs index 061a2499..e80e21c4 100644 --- a/src/config.rs +++ b/src/config.rs @@ -559,6 +559,7 @@ impl Default for HtmlConfig { search: None, git_repository_url: None, git_repository_icon: None, + git_repository_edit_url_template: None, input_404: None, site_url: None, cname: None, diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index 9279d5d3..e1cbab71 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -40,7 +40,12 @@ impl HtmlHandlebars { if let Some(ref git_repository_edit_url_template) = ctx.html_config.git_repository_edit_url_template { - let full_path = "src/".to_owned() + path.to_str().unwrap(); + let full_path = "src/".to_owned() + + ch.source_path + .clone() + .unwrap_or_default() + .to_str() + .unwrap_or_default(); let edit_url = git_repository_edit_url_template.replace("{path}", &full_path); ctx.data .insert("git_repository_edit_url".to_owned(), json!(edit_url)); From c3beecc96ad810f65521ad595d8d79eac6a705c1 Mon Sep 17 00:00:00 2001 From: Flavio Castelli Date: Mon, 19 Apr 2021 19:07:37 +0200 Subject: [PATCH 6/8] Update docs to include example of edit links feature Add a working example of the edit links feature to the examples --- guide/src/format/config.md | 1 + 1 file changed, 1 insertion(+) diff --git a/guide/src/format/config.md b/guide/src/format/config.md index 7b19654b..f43c56a6 100644 --- a/guide/src/format/config.md +++ b/guide/src/format/config.md @@ -295,6 +295,7 @@ additional-js = ["custom.js"] no-section-label = false git-repository-url = "https://github.com/rust-lang/mdBook" git-repository-icon = "fa-github" +git-repository-edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}" site-url = "/example-book/" cname = "myproject.rs" input-404 = "not-found.md" From 94e797fba07fbb457e18f25c9179612d2d2491d4 Mon Sep 17 00:00:00 2001 From: Flavio Castelli Date: Mon, 19 Apr 2021 19:08:15 +0200 Subject: [PATCH 7/8] mdbook book: show edit link Add "edit" links to the pages of mdbook own book --- guide/book.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/guide/book.toml b/guide/book.toml index 6b01202e..f77c28cf 100644 --- a/guide/book.toml +++ b/guide/book.toml @@ -11,6 +11,7 @@ edition = "2018" mathjax-support = true site-url = "/mdBook/" git-repository-url = "https://github.com/rust-lang/mdBook/tree/master/guide" +git-repository-edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}" [output.html.playground] editable = true From 7525b35383355483ce95c36f021342b9dec0ab36 Mon Sep 17 00:00:00 2001 From: Flavio Castelli Date: Mon, 26 Apr 2021 09:59:08 +0200 Subject: [PATCH 8/8] Rename git-repository-edit-url-template Change the name of the git-repository-edit-url-template to be more generic: `edit-url-template` Signed-off-by: Flavio Castelli --- guide/book.toml | 2 +- guide/src/format/config.md | 9 ++++----- src/config.rs | 11 +++++------ src/renderer/html_handlebars/hbs_renderer.rs | 6 ++---- 4 files changed, 12 insertions(+), 16 deletions(-) diff --git a/guide/book.toml b/guide/book.toml index f77c28cf..a37c2a7f 100644 --- a/guide/book.toml +++ b/guide/book.toml @@ -11,7 +11,7 @@ edition = "2018" mathjax-support = true site-url = "/mdBook/" git-repository-url = "https://github.com/rust-lang/mdBook/tree/master/guide" -git-repository-edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}" +edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}" [output.html.playground] editable = true diff --git a/guide/src/format/config.md b/guide/src/format/config.md index f43c56a6..b3110194 100644 --- a/guide/src/format/config.md +++ b/guide/src/format/config.md @@ -201,10 +201,9 @@ The following configuration options are available: an icon link will be output in the menu bar of the book. - **git-repository-icon:** The FontAwesome icon class to use for the git repository link. Defaults to `fa-github`. -- **git-repository-edit-url-template:** Git repository file edit url - template, when provided shows an "Suggest an edit" button for - directly jumping to editing the currently viewed page in the git - repository. For e.g. GitHub projects set this to +- **edit-url-template:** Edit url template, when provided shows a + "Suggest an edit" button for directly jumping to editing the currently + viewed page. For e.g. GitHub projects set this to `https://github.com///edit/master/{path}` or for Bitbucket projects set it to `https://bitbucket.org///src/master/{path}?mode=edit` @@ -295,7 +294,7 @@ additional-js = ["custom.js"] no-section-label = false git-repository-url = "https://github.com/rust-lang/mdBook" git-repository-icon = "fa-github" -git-repository-edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}" +edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}" site-url = "/example-book/" cname = "myproject.rs" input-404 = "not-found.md" diff --git a/src/config.rs b/src/config.rs index e80e21c4..78fdc3ad 100644 --- a/src/config.rs +++ b/src/config.rs @@ -522,11 +522,10 @@ pub struct HtmlConfig { /// /// [custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site pub cname: Option, - /// Git repository file edit url template, when set shows an - /// "Suggest an edit" button for directly jumping to editing the - /// currently viewed page in the git repository. Contains {path} - /// that is replaced with chapter source file path - pub git_repository_edit_url_template: Option, + /// Edit url template, when set shows a "Suggest an edit" button for + /// directly jumping to editing the currently viewed page. + /// Contains {path} that is replaced with chapter source file path + pub edit_url_template: Option, /// This is used as a bit of a workaround for the `mdbook serve` command. /// Basically, because you set the websocket port from the command line, the /// `mdbook serve` command needs a way to let the HTML renderer know where @@ -559,7 +558,7 @@ impl Default for HtmlConfig { search: None, git_repository_url: None, git_repository_icon: None, - git_repository_edit_url_template: None, + edit_url_template: None, input_404: None, site_url: None, cname: None, diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index e1cbab71..56324331 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -37,16 +37,14 @@ impl HtmlHandlebars { _ => return Ok(()), }; - if let Some(ref git_repository_edit_url_template) = - ctx.html_config.git_repository_edit_url_template - { + if let Some(ref edit_url_template) = ctx.html_config.edit_url_template { let full_path = "src/".to_owned() + ch.source_path .clone() .unwrap_or_default() .to_str() .unwrap_or_default(); - let edit_url = git_repository_edit_url_template.replace("{path}", &full_path); + let edit_url = edit_url_template.replace("{path}", &full_path); ctx.data .insert("git_repository_edit_url".to_owned(), json!(edit_url)); }