├── TOC.ini ├── en-US ├── advanced │ ├── README.md │ └── config_cheat_sheet.md ├── faqs │ └── README.md ├── howto │ ├── README.md │ ├── documentation.md │ ├── extension.md │ ├── navbar.md │ ├── pages.md │ ├── protect_resources.md │ ├── static_resources.md │ ├── templates.md │ ├── upgrade.md │ └── webhook.md └── intro │ ├── README.md │ ├── getting_started.md │ ├── installation.md │ └── roadmap.md ├── images └── github_webhook.png └── zh-CN ├── advanced ├── README.md └── config_cheat_sheet.md ├── faqs └── README.md ├── howto ├── README.md ├── documentation.md ├── extension.md ├── navbar.md ├── pages.md ├── protect_resources.md ├── static_resources.md ├── templates.md ├── upgrade.md └── webhook.md └── intro ├── README.md ├── getting_started.md ├── installation.md └── roadmap.md /TOC.ini: -------------------------------------------------------------------------------- 1 | -: intro 2 | -: howto 3 | -: advanced 4 | -: faqs 5 | 6 | [intro] 7 | -: README 8 | -: installation 9 | -: getting_started 10 | -: roadmap 11 | 12 | [howto] 13 | -: README 14 | -: documentation 15 | -: webhook 16 | -: templates 17 | -: static_resources 18 | -: navbar 19 | -: pages 20 | -: extension 21 | -: protect_resources 22 | -: upgrade 23 | 24 | [advanced] 25 | -: README 26 | -: config_cheat_sheet 27 | 28 | [faqs] 29 | -: README -------------------------------------------------------------------------------- /en-US/advanced/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Advanced 3 | --- -------------------------------------------------------------------------------- /en-US/advanced/config_cheat_sheet.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Config Cheat Sheet 3 | --- 4 | 5 | # Configuration Cheat Sheet 6 | 7 | Before we get started, make sure you know that any change of configuration should be made in `custom/app.ini` file, and uses [INI](https://en.wikipedia.org/wiki/INI_file) syntax. 8 | 9 | Also, this document only covers config options that are not mentioned anywhere else in the documentation. 10 | 11 | ## Site 12 | 13 | ```ini 14 | # Site level configuration 15 | [site] 16 | # Name for your Peach instance 17 | NAME = Peach Server 18 | # HTML description meta 19 | DESC = Peach is a web server for multi-language, real-time update and searchable documentation. 20 | # Use CDN to load static resources, but Google Font will always be fetched from CDN 21 | USE_CDN = true 22 | # Your site URL to be accessed by other people 23 | URL = http://localhost:5555 24 | ``` 25 | 26 | ## Page 27 | 28 | ```ini 29 | [page] 30 | # Set to false means no home page for the site, and always redirect users to documentation page 31 | HAS_LANDING_PAGE = true 32 | ``` -------------------------------------------------------------------------------- /en-US/faqs/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: FAQs 3 | --- 4 | 5 | # FAQs 6 | 7 | ### How do I use reverse proxy with NGINX? 8 | 9 | Here is an example of NGINX config section, but values can be different from your situation: 10 | 11 | ```nginx 12 | server { 13 | listen 80; 14 | server_name peachdocs.org; 15 | 16 | location / { 17 | proxy_pass http://localhost:5556; 18 | } 19 | } 20 | ``` 21 | 22 | ### Does my custom directory have to be a Git repository? 23 | 24 | No, your custom directory does not have to be a Git repository, it's just a best practice to sync and backup your custom things. 25 | 26 | ### How do I setup single language documentation? 27 | 28 | By default, Peach requires you have two language versions of documentation (`en-US` and `zh-CN`); otherwise it will give an error about missing documentation. To use single language documentation, you need to make similar changes in your `custom/app.ini` as follows: 29 | 30 | ``` 31 | [i18n] 32 | LANGS = en-US 33 | NAMES = English 34 | ``` 35 | -------------------------------------------------------------------------------- /en-US/howto/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: How do I... 3 | --- -------------------------------------------------------------------------------- /en-US/howto/documentation.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Setup Documentation 3 | --- 4 | 5 | # Setup Documentation 6 | 7 | Every Peach documentation repository should contain two parts of information: 8 | 9 | - TOC.ini 10 | - Documentation for every supported language 11 | 12 | Repository structure should look like as follows: 13 | 14 | ```sh 15 | $ tree 16 | . 17 | ├── TOC.ini 18 | ├── en-US 19 | │   ├── advanced 20 | │   │   ├── README.md 21 | │   │   └── ... 22 | │   ├── faqs 23 | │   │   └── README.md 24 | │   ├── howto 25 | │   │   ├── README.md 26 | │   │   ├── ... 27 | │   └── intro 28 | │   ├── README.md 29 | │   ├── ... 30 | └── zh-CN 31 | │   ├── ... 32 | ``` 33 | 34 | Let me explain them one at a time. 35 | 36 | ## TOC.ini 37 | 38 | In the repository root directory, you must have a file named `TOC.ini`, which stands for **Table Of Contents**. 39 | 40 | In this file, you will use [INI](https://en.wikipedia.org/wiki/INI_file) syntax to define the directories and files, and their organization. 41 | 42 | Here is the `TOC.ini` from [Peach Docs](http://peachdocs.org): 43 | 44 | ```ini 45 | -: intro 46 | -: howto 47 | -: advanced 48 | -: faqs 49 | 50 | [intro] 51 | -: README 52 | -: installation 53 | -: getting_started 54 | -: roadmap 55 | 56 | [howto] 57 | -: README 58 | -: documentation 59 | -: webhook 60 | -: templates 61 | -: static_resources 62 | -: disqus 63 | -: ga 64 | 65 | [advanced] 66 | -: README 67 | -: config_cheat_sheet 68 | 69 | [faqs] 70 | -: README 71 | ``` 72 | 73 | :speech_balloon: Note that Peach only supports single-level directories. 74 | 75 | In the default section, define the directories and their order: 76 | 77 | ```ini 78 | -: intro 79 | -: howto 80 | -: advanced 81 | -: faqs 82 | ``` 83 | 84 | These names are the same as the directory's name. 85 | 86 | Then create a section for each name. The section order doesn't matter: 87 | 88 | ```ini 89 | [intro] 90 | ... 91 | [howto] 92 | ... 93 | [advanced] 94 | ... 95 | [faqs] 96 | ... 97 | ``` 98 | 99 | In each section, define the files and their order: 100 | 101 | ```ini 102 | [intro] 103 | -: README 104 | -: installation 105 | -: getting_started 106 | -: roadmap 107 | ``` 108 | 109 | Because files use Markdown syntax, their names must end with an `.md` extension. However, since we know that, no extension needs to be added in the `TOC.ini` file at all. 110 | 111 | :exclamation: :exclamation: :exclamation: 112 | 113 | - Every section must have at least one key. 114 | - The first key in every section corresponds to the directory's information. 115 | - This file itself will not be shown as a document page, but for the directory. For example, [Introduction](../intro). 116 | - The name of the first key can be anything, but conventionnally, `README` and `README.md` are used as file names. 117 | 118 | ## Localization 119 | 120 | In the repository root directory, every supported language should have a directory with corresponding [Language Culture Name](https://msdn.microsoft.com/en-us/library/ee825488\(v=cs.20\).aspx). 121 | 122 | By default, Peach supports English (`en-US`) and Simplified Chinese (`zh-CN`), so Peach has two directories as follows: 123 | 124 | ```sh 125 | $ tree 126 | . 127 | ├── en-US 128 | │   ├── ... 129 | └── zh-CN 130 | │   ├── ... 131 | ``` 132 | 133 | And of course, both of these directories have exactly the same structure and file name. 134 | 135 | ## Document 136 | 137 | Every file must define itself in the very beginning; real content follows afterwards: 138 | 139 | ``` 140 | --- 141 | name: Introduction 142 | --- 143 | 144 | # Peach 145 | 146 | Peach is a web server for multi-language, real-time synchronization and searchable documentation. 147 | ... 148 | ``` 149 | 150 | If you only need to define information in a directory but it has no content, skip the content: 151 | 152 | ``` 153 | --- 154 | name: Advanced 155 | --- 156 | ``` 157 | 158 | ## Links 159 | 160 | Rendering links in Peach basically works the same way as anywhere else: 161 | 162 | - Link to page in the same level: `[Webhook](webhook)`. 163 | - Link to directory page: `[Introduction](../intro)`. 164 | - Link to page in another directory: `[Getting Started](../intro/getting_started)`. 165 | 166 | ## Images 167 | 168 | By default, documentaion pages have a URL prefix `/docs`, and all your images must be put in a subdirectory of repository root directory named `images`. 169 | 170 | This is how to link a image: `![](/docs/images/github_webhook.png)`. 171 | 172 | ## Configuration 173 | 174 | All configuration changes must be made in file `custom/app.ini`. 175 | 176 | ### Locales 177 | 178 | By default, Peach supports English and Simplified Chinese, so if you're writing documentation for these two languages, you don't need to change settings in this part. 179 | 180 | If you're just writing documentation in English, you would need to rewrite corresponding values: 181 | 182 | ```ini 183 | [i18n] 184 | LANGS = en-US 185 | NAMES = English 186 | ``` 187 | 188 | If you're supporting more than two languages: 189 | 190 | ```ini 191 | [i18n] 192 | LANGS = en-US,zh-CN,fr-FR 193 | NAMES = English,简体中文,Français 194 | ``` 195 | 196 | Note that the first language, `en-US` in both of the examples above, will also be known as **default language**. Any page that is not available in other languages will present content in this language. 197 | 198 | ### Git Repository 199 | 200 | In production, use remote Git source as your documentation repository: 201 | 202 | ```ini 203 | RUN_MODE = prod 204 | 205 | [docs] 206 | TYPE = remote 207 | TARGET = https://github.com/Unknwon/peach-docs.git 208 | TARGET_DIR = # Add subdirectory here if docs are not located in the root directory of your repository 209 | ``` 210 | 211 | :white_flower: `TARGET_DIR` option requires Peach version **0.9.6** 212 | 213 | This means Peach knows where to fetch and update your documentation, and cache all documents. 214 | 215 | ## Developing Locally 216 | 217 | To make your life easier while you're developing your documentation locally, Peach also supports specification of a local target path of your documentation repository: 218 | 219 | ```ini 220 | RUN_MODE = dev 221 | 222 | [docs] 223 | TYPE = local 224 | TARGET = ~unknwon/mydocs 225 | ``` 226 | 227 | In `dev` mode, Peach reloads your documents every time you refresh a page, so you can preview results instantly. 228 | -------------------------------------------------------------------------------- /en-US/howto/extension.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Use Extensions 3 | --- 4 | 5 | # Use Extensions 6 | 7 | ## Search 8 | 9 | Search extension is enabled by default, to disable it: 10 | 11 | ```ini 12 | [extension] 13 | ENABLE_SEARCH = false 14 | ``` 15 | 16 | ## Highlight JS 17 | 18 | Highlight JS is enabled and can not be disabled, but you can customize the theme of it. 19 | 20 | For example, you want to use `zenburn` theme instead of default one. 21 | 22 | You first copy `zenburn.css` and put it into `custom/public/css` directory, then change setings in `custom/app.ini`: 23 | 24 | ```ini 25 | [extension] 26 | HIGHLIGHTJS_CUSTOM_CSS = /css/zenburn.css 27 | ``` 28 | 29 | ## Edit Page 30 | 31 | You can add a button which links to somewhere that people and edit and help improve the documentation. 32 | 33 | To use this extension, you should make corresponding changes of settings as follows: 34 | 35 | ```ini 36 | [extension] 37 | ENABLE_EDIT_PAGE = true 38 | EDIT_PAGE_LINK_FORMAT = https://github.com/peachdocs/docs/blob/master/{lang}/{blob} 39 | ``` 40 | 41 | Don't forget to change to your repository link! 42 | 43 | :white_flower: If you're using Peach with version lower than **0.7.0**, and are using custom templates. Please add following content right before `{{Content|safe}}` in template file `docs.html`: 44 | 45 | ```django 46 | {% if Extension.EnableEditPage %} 47 | {{Tr(Lang, "docs.edit_page")}} 48 | {% endif %} 49 | ``` 50 | 51 | ## Disqus 52 | 53 | To use Disqus extension, you should add a site on [Disqus](https://disqus.com/) first, then make corresponding changes of settings: 54 | 55 | ```ini 56 | [extension] 57 | ENABLE_DISQUS = true 58 | DISQUS_SHORT_NAME = mypeach 59 | ``` 60 | 61 | ## DuoShuo 62 | 63 | :white_flower: Requires Peach version **0.7.1** 64 | 65 | To use DuoShuo extension, you should add a site on [DuoShuo](http://duoshuo.com/) first, then make corresponding changes of settings: 66 | 67 | ```ini 68 | [extension] 69 | ENABLE_DUOSHUO = true 70 | DUOSHUO_SHORT_NAME = mypeach 71 | ``` 72 | 73 | ## Google Analytics 74 | 75 | To use Google Analytics extension, you should add a profile on [Google Analytics](http://www.google.com/analytics/) first, then make corresponding changes of settings: 76 | 77 | ```ini 78 | GA_BLOCK = """""" 86 | ``` 87 | 88 | --- 89 | 90 | As always, you can hack on corresponding `.html` template files to use and add more extensions. -------------------------------------------------------------------------------- /en-US/howto/navbar.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Customize Navbar 3 | --- 4 | 5 | # Customize Navbar 6 | 7 | By default, Peach only shows three items on navbar: 8 | 9 | - Home page 10 | - Documentation page 11 | - GitHub link 12 | 13 | You can customize these items in your `custom/app.ini` file: 14 | 15 | ```ini 16 | [navbar] 17 | -: home 18 | -: documentation 19 | -: github 20 | 21 | [navbar.home] 22 | LOCALE = navbar.home 23 | LINK = / 24 | 25 | [navbar.documentation] 26 | LOCALE = navbar.documentation 27 | LINK = /docs 28 | 29 | [navbar.github] 30 | ICON = github 31 | LOCALE = GitHub 32 | LINK = https://github.com/peachdocs/peach 33 | BLANK = true 34 | ``` 35 | 36 | Or add more items: 37 | 38 | ```ini 39 | [navbar] 40 | -: home 41 | -: download 42 | -: documentation 43 | -: github 44 | 45 | [navbar.home] 46 | ... 47 | [navbar.download] 48 | ... 49 | [navbar.documentation] 50 | ... 51 | [navbar.github] 52 | ... 53 | ``` 54 | 55 | You can see that the order of items are defined in the section `[navbar]`, and in each of those sections, you can define at most four attributes: 56 | 57 | 1. **ICON**: the name of icon in Semantic UI, no icon if it's empty. 58 | 2. **LOCALE**: the value to be translated based on your locale file, and for certain name like "GitHub", you don't define a translation result, so it will not be translated. 59 | 3. **LINK**: link of item, can be internal link like `/docs` or external link like `https://github.com/peachdocs/peach`. 60 | 4. **BLANK**: `true` for open link in a new windows, default is `false`. 61 | 5. **Enabled**: `false` for not rendering the element, default is `true` ( :white_flower: requires Peach version **0.9.8**) 62 | 63 | :bell: You don't need to write or change anything, if your settings are exactly the same as default! This way, you can have most compatible way to work with Peach with possible future updates. 64 | 65 | If you don't like the way Peach presents the navbar, you can always customize it by changing template file `navbar.html`. -------------------------------------------------------------------------------- /en-US/howto/pages.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Add Pages 3 | --- 4 | 5 | # Add Single Pages 6 | 7 | We understand the needs of showing pages as part of website other than the part of documentation, so Peach also supports to specify what files should be treated as single pages. 8 | 9 | In your `TOC.ini` file, add a section named `[pages]`: 10 | 11 | ```ini 12 | [pages] 13 | -: donate 14 | ``` 15 | 16 | Then you should put file(s) is(are) named `donate.md` under root directory of every supported language. 17 | 18 | For example, you support `en-US` and `zh-CN`, then you should have two following files: 19 | 20 | - `/en-US/donate.md` 21 | - `/zh-CN/donate.md` 22 | 23 | However, the **rule of default language** will also apply that if you only have this file in default language version, the content of default language version will be presented when user's preferred language is not default language. 24 | 25 | The URL path to access this page, will then be `/donate`, which is same as file name without `.md` extension. 26 | 27 | Last but not the least, you can have as many as single pages you want, just define them in the `TOC.ini` file. -------------------------------------------------------------------------------- /en-US/howto/protect_resources.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Protect Resources 3 | --- 4 | 5 | # Protect Internal Resources 6 | 7 | :white_flower: Requires Peach version **0.9.0** 8 | 9 | When some documents are internal use only, you can enable protect mode for them. 10 | 11 | What does protect mode do? 12 | 13 | 1. Authentication based on HTTP Basic Authorization. 14 | 2. User defines a list of authorized users along with their password. 15 | 3. User defines a list of resources to be protected and individuals who can access. 16 | 17 | To enable protect mode, you would need to create a file named `protect.ini` and put it in same directory as your `TOC.ini` does. 18 | 19 | Here is an example: 20 | 21 | ```ini 22 | [user] 23 | user1 = 5F4DCC3B5AA765D61D8327DEB882CF99 24 | user2 = xxx 25 | user3 = xxx 26 | 27 | [auth] 28 | howto/documentation = user1,user2,user3 29 | howto/webhook = user1,user2 30 | howto/templates = user1 31 | ``` 32 | 33 | User password must be MD5-encoded, and use comma (`,`) to seperate multiple users. 34 | 35 | Document URLs do not need `/docs/` prefix as you can tell. 36 | 37 | Based on example file, there are three users are authorized, and three resources are protected: 38 | 39 | - `user1` has all access to three resources. 40 | - `user2` can only access `howto/documentation` and `howto/webhook`, and gets **403** when tries to access `howto/templates`. 41 | - `user3` can only access `howto/documentation`, and gets **403** when tries to access `howto/webhook` and `howto/templates`. 42 | - Fail to authenticate will result in **401**. -------------------------------------------------------------------------------- /en-US/howto/static_resources.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Add Static Resources 3 | --- 4 | 5 | # Add Static Resources 6 | 7 | The directory of custom static resources follows the same structure of default ones, and should be put under `custom` directory as well: 8 | 9 | ```sh 10 | $ tree custom/public 11 | custom/public 12 | ├── css 13 | ├── fonts 14 | ├── img 15 | └── js 16 | ``` 17 | 18 | ## Logo 19 | 20 | The very first thing you want to customize is the Logo of your project. 21 | 22 | To do that, rename your Logo file to `favicon.ico` and put it under `custom/public/img` directory: 23 | 24 | ```sh 25 | $ tree custom/public/img 26 | custom/public/img 27 | └── favicon.ico 28 | ``` 29 | 30 | It does not matter what your Logo image format is (PNG, JPEG or whatever), it's just a name convention, and let browser figures it. 31 | 32 | :speech_balloon: You need do a hard refresh on your browser to actually see the effect. 33 | 34 | ## Custom CSS 35 | 36 | By convention, you can create a CSS file named `my.css` under `custom/public/css` directory: 37 | 38 | ```sh 39 | $ tree custom/public/css 40 | custom/public/css 41 | └── my.css 42 | ``` 43 | 44 | And then, change settings on your configuration file `custom/app.ini`: 45 | 46 | ```ini 47 | [asset] 48 | CUSTOM_CSS = /css/my.css 49 | ``` 50 | 51 | ## Custom UI Framework 52 | 53 | In the case you need to completely change a UI framework, you can put all needed static resources on `custom/public` directory and change template file `base.html` to replace old resource links with custom ones: 54 | 55 | ```html 56 | ... 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | ... 65 | ``` -------------------------------------------------------------------------------- /en-US/howto/templates.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Customize Templates 3 | --- 4 | 5 | # Customize Templates 6 | 7 | Default templates are cool and fine, but in many cases you will want to customize them, especially the home page (though it would be awesome if you advertise for Peach :beers:). 8 | 9 | To do that, you need first copy over default template files to `custom` directory in your project directory: 10 | 11 | ```sh 12 | $ cp -r templates custom 13 | $ tree custom/templates 14 | custom/templates 15 | ├── 404.html 16 | ├── base.html 17 | ├── disqus.html 18 | ├── docs.html 19 | ├── footer.html 20 | ├── home.html 21 | ├── navbar.html 22 | └── search.html 23 | 24 | 0 directories, 8 files 25 | ``` 26 | 27 | You now can edit those files to fit your needs. Generally, you only need to edit `home.html` and `footer.html` these two files. 28 | 29 | ## Syntax 30 | 31 | Peach uses Go [Pongo2 v3](https://github.com/flosch/pongo2/tree/v3) as its templating engine, which uses using Django HTML, and syntax is most compatible with [Django 1.7](https://docs.djangoproject.com/en/1.7/ref/templates/builtins/). 32 | 33 | ## UI Framework 34 | 35 | By default, Peach is using [Semantic UI](http://semantic-ui.com/) as its UI framework. 36 | 37 | If you're familiar with it, awesome! But it is **not a requirement**. 38 | 39 | You can change it and use [Bootstrap](http://getbootstrap.com/) as your UI framework because you have full control of how templates are defined. Of course, you need first [import all the static resources](static_resources) you need to the `custom` directory. 40 | 41 | See [example of go-ini/ini package](https://ini.unknwon.io/) which uses [Material Design for Bootstrap](https://mdbootstrap.com/) as its UI Framework. 42 | 43 | ## Localization 44 | 45 | Peach uses [Macaron](http://go-macaron.com/)'s [i18n](http://go-macaron.com/docs/middlewares/i18n) middleware for localization, here is an example how to translate a string in the template: 46 | 47 | ```django 48 |

{{Tr(Lang,"hello %s","world")}}!

49 | ``` 50 | 51 | And a quick example for how to organize your custom locale files (there three supported languages in the example below): 52 | 53 | ```ini 54 | $ tree custom/locale 55 | custom/locale 56 | ├── locale_en-US.ini 57 | ├── locale_fr-FR.ini 58 | └── locale_zh-CN.ini 59 | 60 | 0 directories, 3 files 61 | ``` 62 | 63 | ## Case Studies 64 | 65 | In case you are interested in how other projects customize their templates and locale files: 66 | 67 | - [gogsweb.peach](https://github.com/gogits/gogsweb.peach) 68 | - [ini.peach](https://github.com/go-ini/ini.peach) 69 | -------------------------------------------------------------------------------- /en-US/howto/upgrade.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Upgrade 3 | --- 4 | 5 | # Upgrade Peach 6 | 7 | If you installed Peach from source code, you can then simply execute following command to upgrade Peach binary: 8 | 9 | ```sh 10 | $ go get -u github.com/peachdocs/peach 11 | ``` 12 | 13 | Then in all of your project directories, you should do following steps for each of them: 14 | 15 | 1. Remove current default `conf`, `public` and `templates` directories. 16 | 2. Copy over latest version of those directories. 17 | 3. Check with change log, make sure there is no compatibility issues. 18 | 4. Make necessary changes in your custom `templates` and `public` directories to fix any possible compatibility issues. -------------------------------------------------------------------------------- /en-US/howto/webhook.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Sync with Webhook 3 | --- 4 | 5 | # Sync with Webhook 6 | 7 | Obviously, you don't want to login to your server and update documentation manully every time you make a change, especially when change is very small. 8 | 9 | Peach provides ability to sync your documentation at real-time through webhook. 10 | 11 | So the first thing you need to do is [setting up your documentation](documentation) as a [Git repository](documentation#git-repository). 12 | 13 | You can then set the webhook secret in your `custom/app.ini`: 14 | 15 | ```ini 16 | [docs] 17 | SECRET = mysecret 18 | ``` 19 | 20 | The format and URL path for trigger a hook is `POST /hook?secret={secret}`, you can see `secret` is pass by URL query. 21 | 22 | Note that the `secret` is only valid when URL query and `SECRET` are matched **exactly**, so if `SECRET` is empty, URL query of secret must be empty, vice versa. 23 | 24 | ## GitHub 25 | 26 | Here is an example of how to setup Peach webhook on GitHub, but elsewhere is almost same. 27 | 28 | 1. Go to your documentation repository new webhook page (`/:username/:reponame/settings/hooks/new`) 29 | 2. Fill in **Payload URL** with hook URL path, for example, `http://peachdocs.org/hook?secret=mypeach`. 30 | 3. Click `Add webhook`, and you're all set. :tada: 31 | 32 | ![](/docs/images/github_webhook.png) 33 | 34 | Now every time you push or merge Pull Request on GitHub, your Peach instance will automatically update documentation to the latest version. -------------------------------------------------------------------------------- /en-US/intro/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Introduction 3 | --- 4 | 5 | # Peach 6 | 7 | Peach is a web server for multi-language, real-time synchronization and searchable documentation. 8 | 9 | ## Motivation 10 | 11 | There are some awesome web documentation tools, but for a long time, none of them satisfied my need to post multi-project documentation on the web, so I have been searching for **a common and customizable solution**. This is initally why Peach was created. 12 | 13 | The following table illustrates the main feature differences between Peach and other existing tools (concepts may be different from what I understand): 14 | 15 | |Name|Self-hosted|Multi-language|Real-time Sync|Static HTML|Versionable| 16 | |:--:|:---------:|:------------:|:------------:|:---------:|:---------:| 17 | |Peach|✅|✅|✅|✅(cachable)|[Roadmap](/docs/intro/roadmap)| 18 | |Mkdocs|✅|❌|❌|✅|❌| 19 | |Read The Docs|❌|✅|✅|✅|✅| 20 | 21 | Other than those, Peach also supports following features: 22 | 23 | - Real-time sync from any Git hosting sources. 24 | - Full-text search based on preferred language. 25 | - Use Markdown to write like a writer. 26 | - Highly configurable without touching a single bit of Git history. 27 | - Built-in Disqus integration support. 28 | 29 | ## Development Status 30 | 31 | Peach is currently still in development, but can be used in production with some notes: 32 | 33 | - Things are subject to change, 34 | - ... but if you don't upgrade, it will keep working until the end of the world. :100: 35 | - If you do want to upgrade, just read the documentation. :joy: 36 | 37 | ## Case Studies 38 | 39 | - [Peach Docs](http://peachdocs.org/): [peach.peach](https://github.com/peachdocs/peach.peach) 40 | - [Gogs Docs](http://gogs.io/): [gogsweb.peach](https://github.com/gogits/gogsweb.peach) 41 | - [Macaron Docs](http://go-macaron.com/): [macaron.peach](https://github.com/macaron-contrib/macaron.peach) 42 | - [INI Docs](https://ini.unknwon.io/): [ini.peach](https://github.com/go-ini/ini.peach) 43 | -------------------------------------------------------------------------------- /en-US/intro/getting_started.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Getting Started 3 | --- 4 | 5 | # Getting Started 6 | 7 | Let's create our first Peach project! 8 | 9 | By convention, every Peach project should be named in format `*.peach`, here we choose `my.peach`. 10 | 11 | In this tutorial, we're going to put our Peach project in download directory: 12 | 13 | ```sh 14 | $ cd ~/Downloads 15 | ``` 16 | 17 | Then, we need to setup default things (Suppose `$GOPATH/bin` has been added to your `$PATH`): 18 | 19 | ```sh 20 | $ peach new -target=my.peach 21 | ➜ Creating 'my.peach'... 22 | ➜ Creating 'templates'... 23 | ➜ Creating 'public'... 24 | Do you want to use custom templates?[Y/n] n 25 | ✓ Done! 26 | ``` 27 | 28 | Let's take a quick look of how our project is organized: 29 | 30 | ```sh 31 | $ cd my.peach 32 | $ tree -L 2 33 | . 34 | ├── conf 35 | │   ├── app.ini 36 | │   └── locale 37 | ├── public 38 | │   ├── css 39 | │   ├── fonts 40 | │   ├── img 41 | │   └── js 42 | └── templates 43 | ├── 404.html 44 | ├── base.html 45 | ├── disqus.html 46 | ├── docs.html 47 | ├── duoshuo.html 48 | ├── footer.html 49 | ├── home.html 50 | ├── navbar.html 51 | └── search.html 52 | ``` 53 | 54 | Great! We've got almost everything we need, except one thing: custom configuration. 55 | 56 | To quickly get started with, we are going to use the one Peach uses, it is [open sourced on GitHub](https://github.com/peachdocs/peach.peach). :heart_eyes: 57 | 58 | So... how do we use that? 59 | 60 | Right, we clone it to local system, and name the directory to `custom` which Peach uses it to load all custom things. 61 | 62 | ```sh 63 | git clone https://github.com/peachdocs/peach.peach.git custom 64 | ``` 65 | 66 | Very well! You can't wait to try it out, can you? 67 | 68 | Why don't you now start a Peach server in current directory (in this case, it is `~/Downloads/my.peach`): 69 | 70 | ```sh 71 | $ peach web 72 | ``` 73 | 74 | OK, Peach is now running and you should see log on your terminal: 75 | 76 | ``` 77 | [Peach] 15-10-06 19:58:44 [ INFO] Peach 0.8.0.1025 78 | [Peach] 15-10-06 19:58:44 [ INFO] Peach Server Listen on 0.0.0.0:5556 79 | ``` 80 | 81 | Based on the log, Peach is customized itself to listen on `0.0.0.0:5556` (default is `5555`), and if you open your browser and visit http://localhost:5556/, miracle happens! 82 | 83 | If you curious about what is in Peach's custom configuration, let me briefly explain in the `custom/app.ini` file: 84 | 85 | ```ini 86 | # Change listen port 87 | HTTP_PORT = 5556 88 | 89 | [docs] 90 | # Set documentation to a remote Git source adrress 91 | TYPE = remote 92 | # URL to remote Git source 93 | TARGET = https://github.com/Unknwon/peach-docs.git 94 | ``` 95 | 96 | This should explain why we didn't do anything with documentation but we can view it automatically. 97 | 98 | Well, let's moving forward: [Setup your documentation repository](../howto/documentation). 99 | -------------------------------------------------------------------------------- /en-US/intro/installation.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Installation 3 | --- 4 | 5 | # Installation 6 | 7 | ## From Binary 8 | 9 | You can download binaries of latest release on [GitHub](https://github.com/peachdocs/peach/releases). 10 | 11 | ## From Source Code 12 | 13 | Install from source code requires you have setup [Go](https://golang.org/) environment and set `$GOPATH` variable correctly. 14 | 15 | You can check them with following commands: 16 | 17 | ```sh 18 | $ go version 19 | go version go1.5.1 darwin/amd64 20 | $ echo $GOPATH 21 | ~unknwon/go 22 | ``` 23 | 24 | The minimum requirement version of Go is **1.3**. 25 | 26 | You can then install Peach by executing following command: 27 | 28 | ```sh 29 | go get github.com/peachdocs/peach 30 | ``` 31 | 32 | Add `-u` flag to update Peach: 33 | 34 | ```sh 35 | go get -u github.com/peachdocs/peach 36 | ``` 37 | 38 | You can then use following command to check which version of Peach is installed on your system (Suppose `$GOPATH/bin` has been added to your `$PATH`): 39 | 40 | ```sh 41 | $ peach -v 42 | Peach version 0.9.2.1214 43 | ``` 44 | -------------------------------------------------------------------------------- /en-US/intro/roadmap.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Roadmap 3 | --- 4 | 5 | # Roadmap 6 | 7 | If you find some features are missing in the latest release, and you don't see them on the list, feel free to [file an issue](https://github.com/peachdocs/peach/issues). 8 | 9 | List is ordered by the priority of implementation and may be changed: 10 | 11 | - Versionable (branch and tag) -------------------------------------------------------------------------------- /images/github_webhook.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/peachdocs/docs/760e0641b4de91ef086e826fd179e14c0150fb9f/images/github_webhook.png -------------------------------------------------------------------------------- /zh-CN/advanced/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 高级用法 3 | --- -------------------------------------------------------------------------------- /zh-CN/advanced/config_cheat_sheet.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 配置完全手册 3 | --- 4 | 5 | # 配置文件完全手册 6 | 7 | 在阅读本文档之前，您必须确保您已经了解所有的改动都必须发生在 `custom/app.ini` 文件中，并且使用 [INI](https://en.wikipedia.org/wiki/INI_file) 语法。 8 | 9 | 另外，该文档将只描述其它页面没有提及到的配置选项。 10 | 11 | ## 站点配置 12 | 13 | ```ini 14 | [site] 15 | # Peach 实例的名称 16 | NAME = Peach Server 17 | # HTML 描述 18 | DESC = Peach is a web server for multi-language, real-time update and searchable documentation. 19 | # 使用 CDN 来加载静态资源，但 Google Font 将总是从 CDN 加载 20 | USE_CDN = true 21 | # 外部访问站点的 URL 22 | URL = http://localhost:5555 23 | ``` 24 | 25 | ## 页面配置 26 | 27 | ```ini 28 | [page] 29 | # 设为 false 表示站点没有首页，用户将总是被自动重定向到文档页面 30 | HAS_LANDING_PAGE = true 31 | ``` -------------------------------------------------------------------------------- /zh-CN/faqs/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 常见问题 3 | --- 4 | 5 | # 常见问题 6 | 7 | ### 如何使用 NGINX 进行反向代理？ 8 | 9 | 下面是一个 NGINX 的示例配置分区，但需要注意值可能和实际情况有所不同： 10 | 11 | ```nginx 12 | server { 13 | listen 80; 14 | server_name peachdocs.org; 15 | 16 | location / { 17 | proxy_pass http://localhost:5556; 18 | } 19 | } 20 | ``` 21 | 22 | ### 自定义目录必须是一个 Git 仓库吗？ 23 | 24 | 不是的，自定义目录可以只是一个普通的目录。但一般推荐将它保存为一个 Git 仓库以方便同步和备份。 25 | 26 | ### 我只有单语言版本怎么办？ 27 | 28 | Peach 默认不是单语言的，如果只有简体中文（或者其他）单个语言的文档则会出现运行错误。您可以通过对 `custom/app.ini` 文件进行以下类似的修改来实现单语言文档的需求： 29 | 30 | ``` 31 | [i18n] 32 | LANGS = zh-CN 33 | NAMES = 简体中文 34 | ``` 35 | -------------------------------------------------------------------------------- /zh-CN/howto/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 如何... 3 | --- -------------------------------------------------------------------------------- /zh-CN/howto/documentation.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 创建文档仓库 3 | --- 4 | 5 | # 创建文档仓库 6 | 7 | 每一个 Peach 文档仓库都包含两部分内容： 8 | 9 | - TOC.ini 10 | - 针对每个语言的文档 11 | 12 | 仓库结构大致如下： 13 | 14 | ```sh 15 | $ tree 16 | . 17 | ├── TOC.ini 18 | ├── en-US 19 | │   ├── advanced 20 | │   │   ├── README.md 21 | │   │   └── ... 22 | │   ├── faqs 23 | │   │   └── README.md 24 | │   ├── howto 25 | │   │   ├── README.md 26 | │   │   ├── ... 27 | │   └── intro 28 | │   ├── README.md 29 | │   ├── ... 30 | └── zh-CN 31 | │   ├── ... 32 | ``` 33 | 34 | 让我娓娓道来它们都是做什么的。:trollface: 35 | 36 | ## TOC.ini 37 | 38 | 在仓库的根目录，您必须创建一个名为 `TOC.ini` 的文件，也就是所谓的 **Table Of Content**。 39 | 40 | 在这个文件中，您需要使用 [INI](https://en.wikipedia.org/wiki/INI_file) 语法来定义显示哪些目录和文件，以及它们的显示顺序。 41 | 42 | 下面为 [Peach 文档](http://peachdocs.org) 的 `TOC.ini` 文件： 43 | 44 | ```ini 45 | -: intro 46 | -: howto 47 | -: advanced 48 | -: faqs 49 | 50 | [intro] 51 | -: README 52 | -: installation 53 | -: getting_started 54 | -: roadmap 55 | 56 | [howto] 57 | -: README 58 | -: documentation 59 | -: webhook 60 | -: templates 61 | -: static_resources 62 | -: disqus 63 | -: ga 64 | 65 | [advanced] 66 | -: README 67 | -: config_cheat_sheet 68 | 69 | [faqs] 70 | -: README 71 | ``` 72 | 73 | :speech_balloon: 您可能已经注意到，Peach 只支持一层目录结构。 74 | 75 | 在默认分区中，您可以定义显示哪些目录以及它们的显示顺序： 76 | 77 | ```ini 78 | -: intro 79 | -: howto 80 | -: advanced 81 | -: faqs 82 | ``` 83 | 84 | 这些名称必须和目录名称一致。 85 | 86 | 然后再为每一个目录创建一个分区，顺序在这里是无所谓的： 87 | 88 | ```ini 89 | [intro] 90 | ... 91 | [howto] 92 | ... 93 | [advanced] 94 | ... 95 | [faqs] 96 | ... 97 | ``` 98 | 99 | 在每个分区中，您可以定义显示哪些文件以及它们的显示顺序： 100 | 101 | ```ini 102 | [intro] 103 | -: README 104 | -: installation 105 | -: getting_started 106 | -: roadmap 107 | ``` 108 | 109 | 因为文件已经默认使用 Markdown 语法，并且必须以 `.md` 作为扩展名，所以您完全不需要在 `TOC.ini` 文件中说明。 110 | 111 | :exclamation: :exclamation: :exclamation: 112 | 113 | - 每个分区必须至少包含一个键 114 | - 每个分区的第一个键用于指示该目录的信息 115 | - 这个文件本身不会作为文档单独显示，但是会以目录的形式显示。例如：[简介](../intro) 116 | - 该键的名称是随意的，但一般约定使用 `README`，即使用 `README.md` 作为文件名 117 | 118 | ## 本地化 119 | 120 | 在仓库的根目录，您需要为每个支持的语言创建一个名称符合 [Language Culture Name](https://msdn.microsoft.com/en-us/library/ee825488\(v=cs.20\).aspx) 的相应目录。 121 | 122 | Peach 已经默认支持英语（`en-US`）和简体中文（`zh-CN`），所以 Peach 文档的目录结构为： 123 | 124 | ```sh 125 | $ tree 126 | . 127 | ├── en-US 128 | │   ├── ... 129 | └── zh-CN 130 | │   ├── ... 131 | ``` 132 | 133 | 当然，这两个目录拥有完全相同的目录结构和文件名称。 134 | 135 | ## 文档内容 136 | 137 | 每个文件都必须在最开头的部分定义自身的信息，然后才是文档的内容： 138 | 139 | ``` 140 | --- 141 | name: 简介 142 | --- 143 | 144 | # Peach 145 | 146 | Peach 是一款支持多语言、实时同步以及全文搜索功能的 Web 文档服务器。 147 | ... 148 | ``` 149 | 150 | 如果您的目录不包含任何文档内容，只是代表分类，则可以省略文档部分： 151 | 152 | ``` 153 | --- 154 | name: 高级用法 155 | --- 156 | ``` 157 | 158 | ## 链接跳转 159 | 160 | Peach 中渲染链接的方式和其它地方大体相同： 161 | 162 | - 链接到相同目录的其它页面：`[Webhook](webhook)`. 163 | - 链接到某个目录：`[Introduction](../intro)`. 164 | - 链接到其它目录下的页面：`[Getting Started](../intro/getting_started)`. 165 | 166 | ## 链接图片 167 | 168 | 默认情况下，所有的文档页面都会使用 `/docs` 作为 URL 前缀。并且您所有的图片都必须存放于仓库根目录下名为 `images` 的子目录。 169 | 170 | 然后通过这种语法来链接图片：`![](/docs/images/github_webhook.png)` 171 | 172 | ## 文档配置 173 | 174 | 所有的配置改动都必须发生在 `custom/app.ini` 文件。 175 | 176 | ### 本地化 177 | 178 | Peach 已经默认支持英语和简体中文，所以如果您的文档正好只支持这两种语言，则不需要进行任何修改。 179 | 180 | 但是，如果您只书写英语文档，则必须对配置进行重写： 181 | 182 | ```ini 183 | [i18n] 184 | LANGS = en-US 185 | NAMES = English 186 | ``` 187 | 188 | 或者您支持两种以上语言： 189 | 190 | ```ini 191 | [i18n] 192 | LANGS = en-US,zh-CN,fr-FR 193 | NAMES = English,简体中文,Français 194 | ``` 195 | 196 | 在以上两个例子中，它们的第一个语言都是 `en-US`，第一个语言又被称之为 **默认语言**，如果某个页面在首选语言中不存在，则会自动显示默认语言的版本。 197 | 198 | ### Git 仓库 199 | 200 | 在部署环境下，一般建议使用远程 Git 源来作为您的文档仓库： 201 | 202 | ```ini 203 | RUN_MODE = prod 204 | 205 | [docs] 206 | TYPE = remote 207 | TARGET = https://github.com/Unknwon/peach-docs.git 208 | TARGET_DIR = # 如果文档不是在仓库的根目录，可以在此处添加子目录名称 209 | ``` 210 | 211 | :white_flower: `TARGET_DIR` 选项要求 Peach 版本不得低于 **0.9.6** 212 | 213 | 如此一来，Peach 就知道去哪里拉取和更新文档，并对文档进行缓存。 214 | 215 | ## 本地开发 216 | 217 | 很显然，您会有本地书写开发文档的需求，因此 Peach 也支持将文档同步类型设置为本地： 218 | 219 | ```ini 220 | RUN_MODE = dev 221 | 222 | [docs] 223 | TYPE = local 224 | TARGET = ~unknwon/mydocs 225 | ``` 226 | 227 | 在 `dev` 模式下，Peach 会在每次访问文档页面时重新加载并渲染相应的文档，从而也就达到实时预览效果的需求。 -------------------------------------------------------------------------------- /zh-CN/howto/extension.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 使用扩展功能 3 | --- 4 | 5 | # 使用扩展功能 6 | 7 | ## 搜索 8 | 9 | 搜索扩展处于默认开启状态，修改以下配置可以禁用该扩展： 10 | 11 | ```ini 12 | [extension] 13 | ENABLE_SEARCH = false 14 | ``` 15 | 16 | ## Highlight JS 17 | 18 | Highlight JS 默认启用且不可关闭，但可以自定义它的渲染主题。 19 | 20 | 例如，您希望将默认主题替换为 `zenburn`，则需要先将 `zenburn.css` 文件拷贝至 `custom/public/css` 目录下，然后在 `custom/app.ini` 文件中做出如下修改： 21 | 22 | ```ini 23 | [extension] 24 | HIGHLIGHTJS_CUSTOM_CSS = /css/zenburn.css 25 | ``` 26 | 27 | ## 编辑页面 28 | 29 | 您可以在文档页面添加一个编辑页面的链接以方便用户一同协助改进文档。 30 | 31 | 您需要对配置文件做出相应的修改才能使用该扩展： 32 | 33 | ```ini 34 | [extension] 35 | ENABLE_EDIT_PAGE = true 36 | EDIT_PAGE_LINK_FORMAT = https://github.com/peachdocs/docs/blob/master/{lang}/{blob} 37 | ``` 38 | 39 | 请不要忘记将链接修改为您的仓库链接！ 40 | 41 | :white_flower: 如果您正在使用低于 **0.7.0** 版本的 Peach，并且使用了自定义模板，则需要在 `docs.html` 模板文件的 `{{Content|safe}}` 这一行之前加入以下内容： 42 | 43 | ```django 44 | {% if Extension.EnableEditPage %} 45 | {{Tr(Lang, "docs.edit_page")}} 46 | {% endif %} 47 | ``` 48 | 49 | ## Disqus 50 | 51 | 您需要在 [Disqus](https://disqus.com/) 上添加一个站点后才能使用 Disqus 扩展，然后做出相应的配置修改： 52 | 53 | ```ini 54 | [extension] 55 | ENABLE_DISQUS = true 56 | DISQUS_SHORT_NAME = mypeach 57 | ``` 58 | 59 | ## 多说 60 | 61 | :white_flower: 要求 Peach 版本不得低于 **0.7.1** 62 | 63 | 您需要在 [DuoShuo](http://duoshuo.com/) 上添加一个站点后才能使用多说扩展，然后做出相应的配置修改： 64 | 65 | ```ini 66 | [extension] 67 | ENABLE_DUOSHUO = true 68 | DUOSHUO_SHORT_NAME = mypeach 69 | ``` 70 | 71 | ## Google Analytics 72 | 73 | 您需要在 [Google Analytics](http://www.google.com/analytics/) 上创建一份档案后才能使用 Google Analytics 扩展，然后做出相应的配置修改： 74 | 75 | ```ini 76 | GA_BLOCK = """""" 84 | ``` 85 | 86 | --- 87 | 88 | 由于您对模板文件拥有完全的自定义能力，因此总是可以通过修改相应的 `.html` 模板文件来达到使用或添加更多扩展的需求。 -------------------------------------------------------------------------------- /zh-CN/howto/navbar.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 自定义导航栏 3 | --- 4 | 5 | # 自定义导航栏 6 | 7 | Peach 的导航栏默认包含 3 个链接： 8 | 9 | - 首页 10 | - 文档首页 11 | - GitHub 链接 12 | 13 | 您可以通过修改配置文件 `custom/app.ini` 来自定义导航栏中已有的链接： 14 | 15 | ```ini 16 | [navbar] 17 | -: home 18 | -: documentation 19 | -: github 20 | 21 | [navbar.home] 22 | LOCALE = navbar.home 23 | LINK = / 24 | 25 | [navbar.documentation] 26 | LOCALE = navbar.documentation 27 | LINK = /docs 28 | 29 | [navbar.github] 30 | ICON = github 31 | LOCALE = GitHub 32 | LINK = https://github.com/peachdocs/peach 33 | BLANK = true 34 | ``` 35 | 36 | 或者添加新的链接： 37 | 38 | ```ini 39 | [navbar] 40 | -: home 41 | -: download 42 | -: documentation 43 | -: github 44 | 45 | [navbar.home] 46 | ... 47 | [navbar.download] 48 | ... 49 | [navbar.documentation] 50 | ... 51 | [navbar.github] 52 | ... 53 | ``` 54 | 55 | 其中，`[navbar]` 分区指定了链接的显示顺序，然后在每个下属分区中，最多可以指定五个属性： 56 | 57 | 1. **ICON**：Semantic UI 中图标的样式名称，留空表示没有图标 58 | 2. **LOCALE**：等待被翻译的本地化字符串，但当遇到如 “GitHub” 这样的特有名词，您不需要指定翻译结果，则该字符串就不会被翻译 59 | 3. **LINK**：链接的具体地址，可以是内部链接 `/docs` 或外部链接 `https://github.com/peachdocs/peach` 60 | 4. **BLANK**：值为 `true` 表示使用新窗口打开链接，默认为 `false` 61 | 5. **Enabled**：值为 `false` 表示不渲染该元素，默认为 `true`（ :white_flower: 该选项要求 Peach 版本不得低于 **0.9.8**） 62 | 63 | :bell: 如果您的实际配置和默认的一样，则不需要书写或修改任何内容！这样一来，才能够最大程度保证 Peach 更新后与现有配置的兼容性。 64 | 65 | 当然，如果您觉得 Peach 显示导航栏的方式太搓了，完全可以通过修改模板文件 `navbar.html` 来实现更加高程度的自定义。 -------------------------------------------------------------------------------- /zh-CN/howto/pages.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 添加单独页面 3 | --- 4 | 5 | # 添加单独页面 6 | 7 | 我们有时候都会有显示单独的页面来作为网站的一部分，而不是文档的一部分的需求。因此，Peach 也支持自定义某些文档为单独页面。 8 | 9 | 在 `TOC.ini` 文件中，添加一个名为 `[pages]` 的分区： 10 | 11 | ```ini 12 | [pages] 13 | -: donate 14 | ``` 15 | 16 | 然后，您就可以将名称为 `donate.md` 的文件放置在每一个支持语言的目录下。 17 | 18 | 例如，所支持的语言为 `en-US` 和 `zh-CN`，那么您应该拥有以下两个文件： 19 | 20 | - `/en-US/donate.md` 21 | - `/zh-CN/donate.md` 22 | 23 | 但是，**默认语言规则** 同样适用于单独页面，如果某个页面没有用户当前浏览语言的版本，则会自动显示默认语言的版本。 24 | 25 | 访问该页面的 URL 路径为 `/donate`，即与不包含 `.md` 后缀的文件名称相同。 26 | 27 | 最后要说明的是，您可以在 `TOC.ini` 文件中定义任意多个单独页面。 -------------------------------------------------------------------------------- /zh-CN/howto/protect_resources.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 资源保护 3 | --- 4 | 5 | # 保护内部资源 6 | 7 | :white_flower: 要求 Peach 版本不得低于 **0.9.0** 8 | 9 | 当有些内部资源需要限制访问时，可以对此类资源启用保护模式。 10 | 11 | 那么，保护模式有什么用？ 12 | 13 | 1. 基于 HTTP 基本授权进行认证 14 | 2. 用户定义一组授权用户和他们的密码 15 | 3. 用户定义一组受保护的资源以及允许访问的用户 16 | 17 | 您可以通过在和 `TOC.ini` 文件的相同目录下创建 `protect.ini` 文件来启用保护模式。 18 | 19 | 下面是一个示例文件： 20 | 21 | ```ini 22 | [user] 23 | user1 = 5F4DCC3B5AA765D61D8327DEB882CF99 24 | user2 = xxx 25 | user3 = xxx 26 | 27 | [auth] 28 | howto/documentation = user1,user2,user3 29 | howto/webhook = user1,user2 30 | howto/templates = user1 31 | ``` 32 | 33 | 用户的密码必须经过 MD5 编码，多个用户之间需要使用逗号（`,`）分隔。 34 | 35 | 同时，文档的 URL 不需要添加 `/docs/` 前缀。 36 | 37 | 基于上面的文件，我们定义了 3 个授权用户和 3 个受保护的资源： 38 | 39 | - `user1` 可以访问所有资源。 40 | - `user2` 只能访问 `howto/documentation` 和 `howto/webhook`，尝试访问 `howto/templates` 将返回 **403** 错误。 41 | - `user3` 只能访问 `howto/documentation`，尝试访问 `howto/webhook` 和 `howto/templates` 将返回 **403** 错误。 42 | - 认证失败将返回 **401** 错误。 -------------------------------------------------------------------------------- /zh-CN/howto/static_resources.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 添加静态资源 3 | --- 4 | 5 | # 添加静态资源 6 | 7 | 自定义静态资源的目录同样需要被放置在 `custom` 目录中，并且与默认的静态资源目录具有相同的目录结构： 8 | 9 | ```sh 10 | $ tree custom/public 11 | custom/public 12 | ├── css 13 | ├── fonts 14 | ├── img 15 | └── js 16 | ``` 17 | 18 | ## Logo 19 | 20 | 自定义站点的第一步就是将默认的 Logo 替换为您项目的 Logo。 21 | 22 | 因此，您需要将 Logo 文件重命名为 `favicon.ico` 然后放置到 `custom/public/img` 目录中： 23 | 24 | ```sh 25 | $ tree custom/public/img 26 | custom/public/img 27 | └── favicon.ico 28 | ``` 29 | 30 | 无论 Logo 文件的格式是什么（PNG、JPEG 或其它），都必须遵守该名称约定，浏览器会自动识别并展示图片。 31 | 32 | :speech_balloon: 您需要强制刷新浏览器以查看最终效果。 33 | 34 | ## 自定义 CSS 35 | 36 | 根据约定，您可以在 `custom/public/css` 目录中创建一个名为 `my.css` 的 CSS 文件： 37 | 38 | ```sh 39 | $ tree custom/public/css 40 | custom/public/css 41 | └── my.css 42 | ``` 43 | 44 | 然后在 `custom/app.ini` 文件中修改相关配置： 45 | 46 | ```ini 47 | [asset] 48 | CUSTOM_CSS = /css/my.css 49 | ``` 50 | 51 | ## 自定义 UI 框架 52 | 53 | 如果您需要完全自定义一个其它的 UI 框架，则可以将所有需要的静态资源都放置到 `custom/public` 目录中，然后对 `base.html` 模板文件中的旧链接进行替换： 54 | 55 | ```html 56 | ... 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | ... 65 | ``` -------------------------------------------------------------------------------- /zh-CN/howto/templates.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 自定义模板 3 | --- 4 | 5 | # 自定义模板文件 6 | 7 | 默认的模板文件看起来已经十分完（er）美（bi），但很多情况下您依旧会希望对它们进行自定义，尤其是主页（当然，我不介意您给 Peach 做免费的推广 :beers:）。 8 | 9 | 首先，您需要复制默认的模板文件到您项目目录下的 `custom` 目录： 10 | 11 | ```sh 12 | $ cp -r templates custom 13 | $ tree custom/templates 14 | custom/templates 15 | ├── 404.html 16 | ├── base.html 17 | ├── disqus.html 18 | ├── docs.html 19 | ├── footer.html 20 | ├── home.html 21 | ├── navbar.html 22 | └── search.html 23 | 24 | 0 directories, 8 files 25 | ``` 26 | 27 | 接下来，就可以随意编辑这些文件啦！不过一般来说，您只需要修改 `home.html` 和 `footer.html` 这两个文件。 28 | 29 | ## 模板语法 30 | 31 | Peach 使用 Go 语言 [Pongo2 v3 版本](https://github.com/flosch/pongo2/tree/v3) 作为模板引擎，它使用的是 Django HTML 格式，并与 [Django 1.7](https://docs.djangoproject.com/en/1.7/ref/templates/builtins/) 的语法基本兼容。 32 | 33 | ## UI 框架 34 | 35 | Peach 默认使用 [Semantic UI](http://semantic-ui.com/) 作为它的 UI 框架。 36 | 37 | 如果您已经对这款框架非常熟悉，那么最好不过了。但这并 **不是一个硬性要求**。 38 | 39 | 因为 Peach 提供了对模板的完全自定义能力，您可以根据喜好将 UI 框架修改为 [Bootstrap](http://getbootstrap.com/)。当然，这就要求您首先 [导入所有相关的静态资源](static_resources) 到 `custom` 目录中。 40 | 41 | 可以参考 [go-ini/ini 的案例](https://ini.unknwon.io/)，该网站使用了 [Material Design for Bootstrap](https://mdbootstrap.com/) 作为 UI 框架。 42 | 43 | ## 模板本地化 44 | 45 | Peach 使用 [Macaron](http://go-macaron.com/) 框架的 [i18n](http://go-macaron.com/docs/middlewares/i18n) 中间件来实现模板的本地化需求。 46 | 47 | 下面是一个在模板中翻译某个字符串的例子： 48 | 49 | ```django 50 |

{{Tr(Lang,"hello %s","world")}}!

51 | ``` 52 | 53 | 下面是一个如何组织自定义本地化文件的例子（例子中支持 3 种语言）： 54 | 55 | ```ini 56 | $ tree custom/locale 57 | custom/locale 58 | ├── locale_en-US.ini 59 | ├── locale_fr-FR.ini 60 | └── locale_zh-CN.ini 61 | 62 | 0 directories, 3 files 63 | ``` 64 | 65 | ## 案例学习 66 | 67 | 如果您对其它项目如何自定义模板感兴趣，可以参考以下案例： 68 | 69 | - [gogsweb.peach](https://github.com/gogits/gogsweb.peach) 70 | - [ini.peach](https://github.com/go-ini/ini.peach) 71 | -------------------------------------------------------------------------------- /zh-CN/howto/upgrade.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 更新版本 3 | --- 4 | 5 | # 更新版本 6 | 7 | 如果您之前是通过源码安装的 Peach，则可以直接通过执行以下命令来完成 Peach 的二进制升级操作： 8 | 9 | ```sh 10 | $ go get -u github.com/peachdocs/peach 11 | ``` 12 | 13 | 然后在每个项目的目录下，都要按照以下步骤完成升级操作： 14 | 15 | 1. 移除现有的默认 `conf`、`public` 和 `templates` 目录 16 | 2. 重新拷贝这些目录到当前项目中 17 | 3. 检查变更日志，确保没有兼容性问题 18 | 4. 在自定义目录下的 `templates` 和 `public` 目录做出任何需要的修改以修复可能的兼容性问题 -------------------------------------------------------------------------------- /zh-CN/howto/webhook.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 使用 Web 钩子同步 3 | --- 4 | 5 | # 使用 Web 钩子同步文档 6 | 7 | 正常人都不希望自己每次更新文档的时候都要远程登录服务器去进行手动更新操作，特别是进行一些小修改的时候。 8 | 9 | 为此，Peach 提供了通过 Web 钩子来实时同步文档的功能。 10 | 11 | 那么我们要做的第一件事情就是确保通过 [Git 仓库](documentation#git-%E4%BB%93%E5%BA%93) 来 [创建文档仓库](documentation)。 12 | 13 | 然后就可以在 `custom/app.ini` 文件中填写密钥值： 14 | 15 | ```ini 16 | [docs] 17 | SECRET = mysecret 18 | ``` 19 | 20 | 触发钩子的格式和 URL 路径为 `POST /hook?secret={secret}`，其中密钥值 `secret` 是通过 URL 查询的方式传递的。 21 | 22 | 必须注意的是密钥值 `secret` 只有在和 `SECRET` 的值 **完全匹配** 的情况下才视为有效。因此，如果您的 `SECRET` 值为空，则 URL 查询传递的密钥值 `secret` 也必须为空，反之亦然。 23 | 24 | ## GitHub 25 | 26 | 我们在这里阐述一下如何在 GitHub 上设置 Peach 的 Web 钩子，但在其它地方也是基本一样的。 27 | 28 | 1. 访问文档仓库的新增 Web 钩子页面（`/:username/:reponame/settings/hooks/new`） 29 | 2. 填写 **Payload URL** 值为触发钩子的 URL 路径，例如：`http://peachdocs.org/hook?secret=mypeach` 30 | 3. 单击 `Add webhook` 搞定。 :tada: 31 | 32 | ![](/docs/images/github_webhook.png) 33 | 34 | 从此以后，凡是在 GitHub 推送或合并请求，您的文档都会自动更新到最新版本。 -------------------------------------------------------------------------------- /zh-CN/intro/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 简介 3 | --- 4 | 5 | # Peach 6 | 7 | Peach 是一款支持多语言、实时同步以及全文搜索功能的 Web 文档服务器。 8 | 9 | ## 项目初衷 10 | 11 | 目前网络上已经有多款非常棒的 Web 文档工具，但是观察了很久也没有一款完全符合自己的需求。最主要的是，我本身有许多项目的文档需要公布在 Web 上，这才决定着手开发一款新的 Web 文档服务器，希望能够成为一个 **通用但可自定义的解决方案**。 12 | 13 | 下面的表格对比了 Peach 与几款主流文档工具之间主要特性的区别（实际区别可能与我所理解的有偏差）： 14 | 15 | |名称|自助托管|多语言文档|实时同步|静态 HTML|多版本| 16 | |:--:|:---------:|:------------:|:------------:|:---------:|:---------:| 17 | |Peach|✅|✅|✅|✅（可缓存）|[计划中](/docs/intro/roadmap)| 18 | |Mkdocs|✅|❌|❌|✅|❌| 19 | |Read The Docs|❌|✅|✅|✅|✅| 20 | 21 | 除此之外，Peach 还支持以下功能： 22 | 23 | - 从任意 Git 托管源实时同步文档 24 | - 根据首选语言全文搜索文档 25 | - 使用 Markdown 作为文档书写语法 26 | - 高度可自定义，包括模板、配置和 CSS 等 27 | - 内置 Disqus 集成支持 28 | 29 | ## 开发状态 30 | 31 | Peach 目前仍处于开发阶段，但已可被用于生产环境。 32 | 33 | 下面是一些注意事项： 34 | 35 | - 文档和功能表现会根据需要进行变动， 36 | - ... 但如果您不打算升级，则可以一直运行到世界末日。:100: 37 | - 如果您突（shou）然（jian）希望升级，没事，认真阅读文档就好了。:joy: 38 | 39 | ## 案例学习 40 | 41 | - [Peach 文档](http://peachdocs.org/)：[peach.peach](https://github.com/peachdocs/peach.peach) 42 | - [Gogs 文档](http://gogs.io/)：[gogsweb.peach](https://github.com/gogits/gogsweb.peach) 43 | - [Macaron 文档](http://go-macaron.com/)：[macaron.peach](https://github.com/macaron-contrib/macaron.peach) 44 | - [INI 文档](https://ini.unknwon.io/): [ini.peach](https://github.com/go-ini/ini.peach) 45 | -------------------------------------------------------------------------------- /zh-CN/intro/getting_started.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 开始使用 3 | --- 4 | 5 | # 开始使用 6 | 7 | 同志们好！------ 你不是首长！ 8 | 9 | 同志们辛苦了！------ 我忙着创建 Peach 项目呢，别嚷嚷！ 10 | 11 | 根据约定，每个 Peach 项目都以 `*.peach` 的格式命名，在本例中，我们将使用 `my.peach`，并将项目放置在默认的下载目录： 12 | 13 | ```sh 14 | $ cd ~/Downloads 15 | ``` 16 | 17 | 接下来，我们需要做一些基本设定（假设路径 `$GOPATH/bin` 已经被添加到环境变量 `$PATH`）。 18 | 19 | 如果您是通过源码安装 Peach 的，应该执行与以下类似的命令： 20 | 21 | ```sh 22 | $ peach new -target=my.peach 23 | ➜ Creating 'my.peach'... 24 | ➜ Creating 'templates'... 25 | ➜ Creating 'public'... 26 | Do you want to use custom templates?[Y/n] n 27 | ✓ Done! 28 | ``` 29 | 30 | 好了，来看看目前我们的项目是个什么情况吧： 31 | 32 | ```sh 33 | $ cd my.peach 34 | $ tree -L 2 35 | . 36 | ├── conf 37 | │   ├── app.ini 38 | │   └── locale 39 | ├── public 40 | │   ├── css 41 | │   ├── fonts 42 | │   ├── img 43 | │   └── js 44 | └── templates 45 | ├── 404.html 46 | ├── base.html 47 | ├── disqus.html 48 | ├── docs.html 49 | ├── duoshuo.html 50 | ├── footer.html 51 | ├── home.html 52 | ├── navbar.html 53 | └── search.html 54 | ``` 55 | 56 | 不错不错，差不多都搞定了，不过还差一样，是什么呢？当然是自定义配置啦。 57 | 58 | 为了方便起见，我们直接使用 Peach 自己的配置，因为它已经 [开源在 GitHub](https://github.com/peachdocs/peach.peach) 上了。 :heart_eyes: 59 | 60 | 卧槽，这都（shen）可（me）以（gui）？ 61 | 62 | 当然没问题，我们直接克隆到本地系统并命名为 `custom` 即可，因为该名称就是 Peach 用来加载所有自定义设置的目录。 63 | 64 | ```sh 65 | git clone https://github.com/peachdocs/peach.peach.git custom 66 | ``` 67 | 68 | 简单粗暴！请给自己的机智点 32 个赞。:clap: 69 | 70 | 好了，快点在我们的项目目录下（`~/Downloads/my.peach`）运行 Peach 吧： 71 | 72 | ```sh 73 | $ peach web 74 | ``` 75 | 76 | 现在，我们就可以从控制台看到一些日志啦： 77 | 78 | ``` 79 | [Peach] 15-10-06 19:58:44 [ INFO] Peach 0.8.0.1025 80 | [Peach] 15-10-06 19:58:44 [ INFO] Peach Server Listen on 0.0.0.0:5556 81 | ``` 82 | 83 | 从日志说明来看，Peach 将监听的端口自定义为了 `5556`（默认为`5555`）。 84 | 85 | 此时打开浏览器，访问 http://localhost:5556/ ，哈哈哈，我真是太佩服自己了。 86 | 87 | 如果您对 Peach 的自定义配置感兴趣，让我通过 `custom/app.ini` 文件简单地解释一下： 88 | 89 | ```ini 90 | # 修改监听端口 91 | HTTP_PORT = 5556 92 | 93 | [docs] 94 | # 设置文档类型为远程 Git 源 95 | TYPE = remote 96 | # 远程 Git 源的 URL 97 | TARGET = https://github.com/Unknwon/peach-docs.git 98 | ``` 99 | 100 | 现在您应该明白为什么我们之前什么都没做就可以直接浏览文档了吧？ 101 | 102 | 好了，让我们继续学习下一个部分：[创建文档仓库](../howto/documentation)。 103 | -------------------------------------------------------------------------------- /zh-CN/intro/installation.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 下载安装 3 | --- 4 | 5 | # 下载安装 6 | 7 | 由于目前我们没有提供编译好的二进制进行分发，因此您必须知道如何搭建 [Go](https://golang.org/) 语言的开发环境。 8 | 9 | ## 从二进制安装 10 | 11 | 您可以直接从 [GitHub](https://github.com/peachdocs/peach/releases) 上下载最新版本的二进制文件。 12 | 13 | ## 从源码安装 14 | 15 | 从源码安装要求您已经搭建好 [Go](https://golang.org/) 语言的开发环境并正确设置 `$GOPATH` 环境变量。 16 | 17 | 您可以通过以下命令进行检查： 18 | 19 | ```sh 20 | $ go version 21 | go version go1.5.1 darwin/amd64 22 | $ echo $GOPATH 23 | ~unknwon/go 24 | ``` 25 | 26 | 最低要求的 Go 语言版本为 **1.3**。 27 | 28 | 然后，您就可以通过以下命令安装 Peach： 29 | 30 | ```sh 31 | go get github.com/peachdocs/peach 32 | ``` 33 | 34 | 也可以通过使用 `-u` 标志来更新 Peach： 35 | 36 | ```sh 37 | go get -u github.com/peachdocs/peach 38 | ``` 39 | 40 | 然后使用以下命令来检查安装在您系统的 Peach 版本（假设路径 `$GOPATH/bin` 已经被添加到环境变量 `$PATH`）： 41 | 42 | ```sh 43 | $ peach -v 44 | Peach version 0.9.2.1214 45 | ``` 46 | -------------------------------------------------------------------------------- /zh-CN/intro/roadmap.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 开发计划 3 | --- 4 | 5 | # 开发计划 6 | 7 | 如果您未在下方列表中找到您所期望的功能，可以通过 [发起工单](https://github.com/peachdocs/peach/issues) 的形式告知我们。 8 | 9 | 列表根据实现的优先级排序，且可能发生变动： 10 | 11 | - 多版本（支持分支和标签） --------------------------------------------------------------------------------