Site

Site 对象，在直接调用site的时候，指向当前站点，另外也是account.sites获得列表的单个数据类型。

属性

基本属性

key	说明
id	站点 ID
title	网站标题
page_title	如果有设定网站根目录，则是目录名；反之则是网站的标题
account_id	站点对应的账户 ID
utc_offset	相对0时区的偏移，(-12.0~+12.0)
now	网站的当前时间，类型是 Date数据对象
configs	网站设置 (Dashboard) 中填入的各项配置，数据类型: `dict`
index_doc	根目录下以`index`为名的 Post 数据对象，如不存在，返回`None`
token	网站的API Token，凭此可拥有对网站的完全读、写权限
cronjobs	网站当前的 cronjob 列表，数据类型为 `list`, 每个cronjob的数据对象类型为 Cronjob
text_length	字符长度，但不同于 utf8 编码，这是 unicode 编码的计数，一个中文字或者一个字母，都计数为 1
text_words	字数长度，英文的单词计数为1，中日韩文一个字计数为1 (误差率 2% 左右)

注意: text_length & text_words 统计的仅仅针对 public 性质的日志。

域名相关属性

key	说明
domain	网站(单)域名，这个域名总是处于可访问的状态，如果本身未验证，会在末尾自动增加 `.park.bitcron.com` 以保证可访问性
site_domain	相当于网站创建时输入的域名，属于不可变属性
domains	当前网站申明的域名 (包括未验证的)，数据类型为 list
root_domains	数据类型为 `list`，表示根域名，这个域名存在的话，其他账户就不能占用它了
valid_domains	数据类型为 `list`，表示已验证的域名
invalid_domains	数据类型为 `list`，表示未验证(待验证)的域名

图片、头像相关属性

key	说明
avatar	网站(作者)头像，实际上返回`/avatar.png`这个URL，但图片会进行尺寸的压缩(160*160)，头像本身可在`网站设置(dashboard)`中进行设定。
site_avatar	网站头像，实际上返回`/site_avatar.png`这个URL，但图片会进行尺寸的压缩(240*240)，头像本身可在`网站设置(dashboard)`中进行设定。
visitor_avatar	评论列表中，访客头像(非Bitcron用户邮箱能对应的头像)，实际上返回`/visitor.png`这个URL，但图片会进行尺寸的压缩(80*80)，头像本身可在`网站设置(dashboard)`中进行设定。
admin_avatar	评论列表中，网站作者头像，实际上返回`/visitor.png`这个URL，但图片会进行尺寸的压缩(80*80)，头像本身可在`网站设置(dashboard)`中进行设定。
background_image	实际返回 `/bg.jpg` 这样的路径，可在`网站设置(dashboard)`中进行设定。这个属性的调用与否，主要看不同模板的不同表现。

HTML 构建的属性

socials: 网站设置中配置了 Social ID，比如 twitter、微博等信息的，形成的 HTML 片段。
just_socials: 跟site.socials 不同，默认不会载入对应的图标字体文件。
nav: 网站导航的HTML片段，相当于 site.get_nav(auto_frontend=True)。
just_nav: 跟site.nav不一同的是，默认不会载入导航的css样式，需要自行再定义。
footer: 网站设置中配置了底部栏的 HTML 片段。

site.tags

1，site.tags是按照标签对应的文章数，倒序输出，形如:

[('tag 1',3), ('tag 2', 1)]

2，site.tags模板代码示例:

for tag_name, tag_count in site.tags
    span= tag_name
    span= tag_count

3, site.tags统计的是所有staus=public的日志，同时，如果单个tag内含:字符的，则不算入内。

site.configs

site.configs 里的各项，实际上是不固定的，由模板设计者、使用者自行可以调配的；本文档仅对一些常规、默认的属性项进行说明。
有些属性实际上的值是None(不存在)，因为尚未被用户配置过的原因。

key	说明
title	网站标题，同时也会设定到 site.title 中
sub_title	二级标题
keywords	一般无实质意义，主要针对 SEO；前提是在模板中被调用
description	同`keywords`
utc_offset	时区，等同 site.utc_offset
posts_per_page	每页文章数，针对输出文章列表的一些函数调用起作用
images_per_page	每页图片数，针对输出图片列表的一些函数调用起作用
post_content_type	`plain` or `markdown`, 默认是`markdown`格式；如果是`plain`，则调用`post.content`这个属性的时候，会忽略 Markdown 语法(插图除外)。
post_paragraph_indent	`整数`类型，单位`em`，表示文章的首行缩进。
hide_post_prefix	`True/False`，文章的 URL 一般是`/post/xxxxx`，如果设定值为`True`，则对应的 URL 是`/xxxxx`
mathjax & flowchart & echarts	默认皆`False`，如果设定为`True`，则会载入对应的前端 JS 脚本，以渲染 Mathjax、Flowchat、Echarts 对应的片段。
theme	网站应用的主题名，类似`Wiki/Fit`，默认值一般为`Blog/Default`
cache_strategy	站点缓存策略
force_ssl	如果为`True`，则 `http://`形式访问的，强制跳转到对应的`https://`上
hide_comments	如果为 `True`，隐藏系统默认的评论系统。
nav_configs	用户设定的导航项，数据类型`list`，一般也在`导航(Navigation)`中可以通过拖拽的方式可视化的创建
footer	用户设定的页尾 HTML 代码片段
inject_template	用户设定的模板片段，可以被模板引擎渲染，而`footer`是纯 HTML 片段。

注意: 轻易不要调整 utc_offset 这个属性，它产生变化的时候，会影响网站全局时间的呈现；但已经产生、未修改的(时间)数据源则不会变化。一定程度上，这会产生认知上的偏差。

函数

refresh

作用: 更新当前site对象的数据
注意，一般不会使用到这个函数，除非需要对site内的configs进行配置，需要刷新最新的配置，才会调用。

delete

作用: 删除网站，需要输入账户密码进行确认
注意: 需要网站所有者出于登录时才能生效

update_token

作用: 更新当前网站的API Token，并返回最新的Token
注意: 只有在当前账户出于登录的前提下，该函数才会有用。

choose

创建一个站点选择的HTML片段，如果当前页面有when_site_chose这个javascript回调函数，则在使用者选择站点后调用这个函数，并传递一个site_id作为参数。

disable_nav

禁用导航栏，也就是调用 site.nav 不会获得任何内容。

get_nav

作用: 生成站点导航

参数	说明
meta_doc	post 数据对象 (默认为当前文章)，如果其 metadata 有设定 `nav` 这个 list 类型的属性，则以其为导航源
items	类似 [(name1, url1), (name2, url2)] 结构，表示指定的导航源
auto_frontend	默认为 True，表示自动载入一个导航相关的前端资源以呈现其样式
toogle_menu	默认为 False，若为 True，则表示当页面处于移动端设备宽度的时候，导航栏会自动收缩并可点击展开
as_items	默认为 False，表示生成的结果为 HTML；如果为 True，则返回一个 list，其中每个元素为 dict 类型，拥有 name & url 两个基本属性，用于自定义再构建导航的 HTML 代码片段

注意: 如果是用户自定义的导航，其优先级是最高的；如果都没有设定的话，则会自动推算，并且会将所有 status=page 的文章，作为导航中的一项。

Dashboard

configs 的设定

要实现 site.configs 上的各个属性，可以通过在网站目录下的configs文件夹内的 json 文件实现。
configs文件夹内对应的 json 文件内应该是简单的 key-value 结构，最后在同步到 Bitcron 的时候，会自动将对应的 key-value 更新到 site.configs 这个变量中。

Dashboard 的模板

一般来说，我们可以通过Bitcron 默认提供的Dashboard对网站进行设定。而你也可以实现自己的 Dashboard，因为本质上就是更新一个configs/xxxx.json的配置文件，从而扩展更多的自定义属性以实现各种可能。

以下为系统默认提供的Dashboard的页面源码:

html
    +account.need_admin()
    head
        +h.load('/fb_static/lib/pure.css')
        title= site.title or '?'
        +h.mobile_metas
        +h.load('/fb_static/service/dashboard/dash.css')
    body
        {%
            set dash_parts = [
                {
                    'title': 'Site',
                    'url': '',
                    'icon_css': 'fa fa-home',
                    'path': 'configs/site.json',
                    'fields': ['title', 'sub_title', 'keywords@long_str', 'description@text',
                            'posts_per_page', 'images_per_page', '-',
                            'post_content_type', 'post_paragraph_indent','show_toc@bool', 'hide_post_prefix@bool', '-',
                            'mathjax@bool', 'flowchart@bool', 'echarts@bool',]
                },
                {
                    'title': 'Render',
                    'url': 'render',
                    'icon_css': 'fa fa-newspaper-o',
                    'path': 'configs/render.json',
                    'fields': ['theme', 'debug_template@bool', '-', 'cache_strategy', 'force_ssl@bool', 'hide_comments@bool', 'inject_template@text#200'],
                },
                {
                    'title': 'Social ID',
                    'url': 'social',
                    'icon_css': 'fa fa-user',
                    'path': 'configs/social.json',
                    'fields': ['twitter', 'instagram', 'dribbble', 'github', 'quora', 'flickr','weibo', 'facebook', 'vimeo', 'telegram', 'youtube', 'zhihu'],
                },
                {
                    'title': 'Advanced',
                    'url': 'advanced',
                    'icon_css': 'fa fa-wrench',
                    'path': 'configs/advanced.json',
                    'fields': ['admin_name', 'visitor_password`this is a plaintext password`', '-' , 'utc_offset', 'license_function', 'mail_sender`address from Mail Center`', '-', \
                        'domains@list#200`domains to bind, one domain per line`', 'subdomain@list#200`render a post under a subdomain`'],
                },

                {
                    'title': 'Payment',
                    'url': 'payment',
                    'icon_css': 'fa fa-money',
                    'path': 'configs/payment.json',
                    'fields': ['paypal_account','paypal_merchant_id', '-' ,\
                        'alipay_app_id', 'alipay_private_key@text#200`type <auto> to create one private key automaticlly`', 'alipay_public_key@text#100'],
                },
            ]
        %}

        url_path = request.path.split('/')[-1]
        current_part = dash_parts.filter('url', url_path, return_one=True) or dash_parts[0]
        
        .main.pure-g-r
            .menu.pure-u: .pure-menu.pure-menu-open
                a.pure-menu-heading.homepage(target='_blank', href='/') Home
                ul: for part in dash_parts: li
                    admin_url = "/service/admin/%s"%part.url
                    if request.args.site_id
                        admin_url = admin_url + '?site_id=' + request.args.site_id
                    a(href=admin_url, class="selected" if part.path==current_part.path else "")
                        i(class=part.icon_css)
                        span= _(part.title)
            .container
                .header
                    a#logout(href='/logout')
                        i.fa.fa-power-off
                        span= _('Logout')
                +d.config_editor(current_part.path, current_part.fields)
        +h.load('font')

属性
函数
- refresh
- delete
- update_token
- choose
- disable_nav
- get_nav
Dashboard
- configs 的设定
- Dashboard 的模板