diff --git a/README.md b/README.md index 0fe38bc9fc039..4e2fea0edd43c 100644 --- a/README.md +++ b/README.md @@ -46,9 +46,11 @@ Documentation is written in Markdown, which is parsed by [kramdown](https://kram [Read the quick reference](https://kramdown.gettalong.org/quickref.html) -## Layout components +While the server is running, you can also view the [Markdown styleguide](http://0.0.0.0:9000/markdown-styleguide/links/) -While in dev mode, the sidebar includes documentation for the special components available for formatting content. +## Custom components + +While in dev mode, the sidebar includes documentation for the special tags and includes available for formatting content. ## Adding content diff --git a/_config.yml b/_config.yml index 008659bce0826..a2bd8d90b5992 100644 --- a/_config.yml +++ b/_config.yml @@ -3,8 +3,8 @@ description: >- Learn how to use Sentry, configure Sentry clients, and contribute to the open source project on GitHub meta_image: default.png -baseurl: "" -url: "https://docs.sentry.io" +baseurl: '' +url: 'https://docs.sentry.io' twitter_username: getsentry home_url: https://sentry.io @@ -31,12 +31,12 @@ collections: defaults: - scope: - path: "" + path: '' type: pages values: layout: doc - scope: - path: "" + path: '' type: documentation values: layout: doc @@ -47,11 +47,15 @@ defaults: # object does not get clobbered so we use that to only load the dev # in dev mode, and these defaults here are not used in production. - scope: - path: "" + path: '' type: dev_components values: - layout: doc + layout: dev/default permalink: /:path/ + - scope: + path: collections/_dev_components/markdown-styleguide/* + values: + layout: doc assets: source_maps: false # Prefer webpack sourcemaps @@ -70,9 +74,8 @@ assets: - '*.ico' - 'meta/*' - extlinks: - attributes: {rel: nofollow} + attributes: { rel: nofollow } rel_exclude: ['sentry.io', 'getsentry.com'] # Hack to give us an empty array prototype diff --git a/bin/server b/bin/server index e4c432667155c..b27622d8c8185 100755 --- a/bin/server +++ b/bin/server @@ -41,4 +41,4 @@ rm -rf .jekyll-cache yarn (bundle check || bundle install) -./bin/webpack-watch & ./bin/jekyll-watch +./bin/webpack-watch & ./bin/jekyll-watch diff --git a/src/_data/dev_components_categories.yml b/src/_data/dev_components_categories.yml index 40c5e72f59df8..dd0e8b04d8092 100644 --- a/src/_data/dev_components_categories.yml +++ b/src/_data/dev_components_categories.yml @@ -4,6 +4,10 @@ icon: about-the-dsn slug: markdown-styleguide -- title: Layout Components +- title: Includes icon: workflow - slug: layout-components + slug: includes + +- title: Tags + icon: workflow + slug: tags diff --git a/src/_includes/breadcrumbs.html b/src/_includes/breadcrumbs.html index f03769f13019b..5bc081b42a524 100644 --- a/src/_includes/breadcrumbs.html +++ b/src/_includes/breadcrumbs.html @@ -1,5 +1,6 @@ {%- assign __path = page.url | replace: "collections/_documentation/", "" + | replace: "collections/_dev_components/", "" | split: '/' | pop -%} @@ -16,7 +17,11 @@ {%- if __page -%}
  • {{ __page.breadcrumb | default: __page.title }}
    • {%- else -%} - {%- assign __cateogry = site.data.documentation_categories + {%- assign __categories = site.data.documentation_categories -%} + {% if jekyll.environment == "development" %} + {%- assign __categories = __categories | concat: site.data.dev_components_categories -%} + {%- endif -%} + {%- assign __cateogry = __categories | where: 'slug', __segment | first -%} diff --git a/src/_js/lib/DynamicLoad.js b/src/_js/lib/DynamicLoad.js index 4b0733239e910..aacc98033766a 100644 --- a/src/_js/lib/DynamicLoad.js +++ b/src/_js/lib/DynamicLoad.js @@ -95,6 +95,7 @@ class DynamicLoader { $('body').addClass('loading'); loader({ pathname, hash, search }) .then(html => { + $(document).trigger('page.willUpdate'); $('body').removeClass('loading'); if (html) replaceContent(html); done(); diff --git a/src/_js/lib/Sidebar.js b/src/_js/lib/Sidebar.js index f644726da3588..2e916217bc20c 100644 --- a/src/_js/lib/Sidebar.js +++ b/src/_js/lib/Sidebar.js @@ -1,31 +1,35 @@ -const onlyCategories = (i, el) => { - const $parents = $(el).parentsUntil( - '[data-sidebar-root]', - '[data-sidebar-tree]' - ); - return $parents.length === 1; +const filterDepth = depth => { + return (i, el) => { + const $parents = $(el).parentsUntil( + '[data-sidebar-root]', + '[data-sidebar-tree]' + ); + return $parents.length === depth; + }; }; $(document).on('page.didUpdate', function(event) { const $links = $('[data-sidebar-link]'); let $active = $links.filter(`[href="${location.pathname}"]`); + const $categoryTree = $('[data-sidebar-tree]').filter(filterDepth(1)); $active = !!$active.length ? $active - : $('[data-sidebar-tree]') - .filter(onlyCategories) - .eq(0) - .siblings('[data-sidebar-link]'); + : $categoryTree.first().siblings('[data-sidebar-link]'); $links.each((i, el) => { const $el = $(el); $el.toggleClass('active', $el.is($active)); }); + const $sectionTree = $('[data-sidebar-tree]').filter(filterDepth(0)); + const $trees = $('[data-sidebar-tree]'); $trees.each((i, el) => { const $el = $(el); const containsActive = !!$el.has($active.get(0)).length; const isChildOfActive = $el.parent().is($active.parent()); - $el.toggleClass('collapse', !(containsActive || isChildOfActive)); + const isSection = $sectionTree.is($el); + const leaveVisble = containsActive || isChildOfActive || isSection; + $el.toggleClass('collapse', !leaveVisble); }); }); diff --git a/src/_js/main.js b/src/_js/main.js index 577d830aa770e..40a16ecb17317 100644 --- a/src/_js/main.js +++ b/src/_js/main.js @@ -15,6 +15,10 @@ if (process.env.NODE_ENV === 'production') { Raven.config(dsn).install(); } +$(document).on('page.willUpdate', function(event) { + $('[data-toggle="tooltip"]').tooltip('dispose'); +}); + $(document).on('page.didUpdate', function(event) { $('[data-toggle="tooltip"]').tooltip(); }); diff --git a/src/_layouts/dev/default.html b/src/_layouts/dev/default.html new file mode 100644 index 0000000000000..6a78b9c844f86 --- /dev/null +++ b/src/_layouts/dev/default.html @@ -0,0 +1,43 @@ +--- +layout: doc +--- + +{{ page.content }} + +{%- if page.arguments.size > 0 -%} +

    Arguments

    + +
    + {%- for arg in page.arguments -%} + +
    +
    +
    {{ arg.name }}
    + {% if arg.required %}(Required){% else %}(Optional){% endif %} +
    + {{ arg.desc | markdownify }} +
    + {%- endfor -%} +
    +{%- endif -%} + +
    + +{%- for example in page.examples -%} +{%- if example.title -%}

    {{ example.title }}

    {%- endif -%} + + {%- if example.desc -%} + {{ example.desc | liquify | markdownify }} + {%- endif -%} + +

    Source

    + + {%- highlight liquid -%}{{- example.source -}}{%- endhighlight -%} + +

    Output

    + +
    + {{ example.output | default: example.source | liquify | markdownify }} +
    + +{%- endfor -%} diff --git a/src/collections/_dev_components/includes/alert.md b/src/collections/_dev_components/includes/alert.md new file mode 100644 index 0000000000000..1db0d4dbaf5af --- /dev/null +++ b/src/collections/_dev_components/includes/alert.md @@ -0,0 +1,43 @@ +--- +title: Alert +arguments: + - name: content="" + type: String + required: true + desc: Content for the alert + - name: title="" + type: String + required: false + desc: Title for the alert + - name: level="" + type: String + required: false + desc: Severity of the alert. Must be a valid [Bootstrap severity level](https://getbootstrap.com/docs/4.0/components/alerts/). +examples: + - title: Basic use + source: | + {% include components/alert.html + content="This is the body of the alert" + %} + - title: Full markdown content + source: | + {% capture markdown_content %} + This paragraph explains that it will be followed by a list. + + - This list has three items + - This is the second item + - The last item is the best + {% endcapture %} + {% include components/alert.html + content=markdown_content + %} + - title: Kitchen sink + source: | + {% include components/alert.html + title="Pay attention" + content="This is the body of the alert" + level="danger" + %} +--- + +A box with content, with optional colors diff --git a/src/collections/_dev_components/layout-components/platform-content/example_1/javascript.md b/src/collections/_dev_components/includes/platform-content/example-1/javascript.md similarity index 100% rename from src/collections/_dev_components/layout-components/platform-content/example_1/javascript.md rename to src/collections/_dev_components/includes/platform-content/example-1/javascript.md diff --git a/src/collections/_dev_components/layout-components/platform-content/example_1/python.md b/src/collections/_dev_components/includes/platform-content/example-1/python.md similarity index 100% rename from src/collections/_dev_components/layout-components/platform-content/example_1/python.md rename to src/collections/_dev_components/includes/platform-content/example-1/python.md diff --git a/src/collections/_dev_components/layout-components/platform-content/example_1/ruby.md b/src/collections/_dev_components/includes/platform-content/example-1/ruby.md similarity index 100% rename from src/collections/_dev_components/layout-components/platform-content/example_1/ruby.md rename to src/collections/_dev_components/includes/platform-content/example-1/ruby.md diff --git a/src/collections/_dev_components/includes/platform-content/index.md b/src/collections/_dev_components/includes/platform-content/index.md new file mode 100644 index 0000000000000..5ff181a63d1b6 --- /dev/null +++ b/src/collections/_dev_components/includes/platform-content/index.md @@ -0,0 +1,32 @@ +--- +title: Platform Content +example_string: Hello World +arguments: + - name: 'content_dir="my-example"' + type: String + required: true + desc: Name of the folder where the examples are stored, relative to the current document +examples: + - title: Basic use + desc: | + #### File Structure + + ``` + _documentation/this-category/ + this-document.md + example-1/ + javascript.md + python.md + ruby.md + ``` + source: | + {% include components/platform_content.html content_dir="example_1" %} +--- + +You can customize content by platform. Within a folder in the same directory as your document, add a file for each platform you would like to include, ensuring that name of the file matches a slug in *src/data/platforms.yml*, then use the include to specify which folder to include examples from. + +Content is run through the Liquid compiler, then through the Markdown compiler, making it possible to create dynamic, rich styled content. + +The switcher will globally remember the prefered language and load it by default until changed. If no prefered language is set, the first langage provided is the default. A content platform content block does not contain the preferred language, it will display the default language for the block. + +You may force the platform that is displayed on the page by appending a `platform=javascript` query parameter to the page url. This will cause subsequent pages in the browsing session to display that platform. Removing the query parameter will set the page back to the default behavior of looking for the prefered platform diff --git a/src/collections/_dev_components/includes/user-content.md b/src/collections/_dev_components/includes/user-content.md new file mode 100644 index 0000000000000..fc3a9252a0910 --- /dev/null +++ b/src/collections/_dev_components/includes/user-content.md @@ -0,0 +1,21 @@ +--- +title: User Content +examples: + - title: Basic use + desc: | + {% include components/alert.html content="Do not copy and paste from this example. It contains invisible characters that prevent the tokens from rendering." %} + source: | + ```javascript + console.log("Your DSN is _⁣__DSN___") + ``` + output: | + ```javascript + console.log("Your DSN is ___DSN___") + ``` +--- + +It is possible to display a user's actual configuration information within code samples. This is done using one of the following keys: + +
    + +This feature only works within block level code examples, which are created using tripple tick ``` fenced code blocks in Markdown or using Jekyll's `highlight` tag. diff --git a/src/collections/_dev_components/layout-components/alert.md b/src/collections/_dev_components/layout-components/alert.md deleted file mode 100644 index 925c993e2f84e..0000000000000 --- a/src/collections/_dev_components/layout-components/alert.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Alert -source: components/alert.html ---- - -- `title="note"` _(optional)_ Title for the alert -- `content=""` _(required)_ Content for the alert -- `level="warning"` _(optional)_ Severity of the alert. Must be a valid [Bootstrap severity level][bs-alert]. - -
    - -### Basic use - -#### Source - -```liquid -{% raw %}{% include components/alert.html - content="This is the body of the alert" -%}{% endraw %} -``` - -#### Output - -
    - {% include components/alert.html - content="This is the body of the alert" - %} -
    - -### Full markdown content - -#### Source - -```liquid -{% raw %}{% capture markdown_content %} -This paragraph explains that it will be followed by a list. - -- This list has three items -- This is the second item -- The last item is the best -{% endcapture %} -{% include components/alert.html - content=markdown_content -%}{% endraw %} -``` - -#### Output - -
    - {% capture markdown_content %} - This paragraph explains that it will be followed by a list. - - - This list has three items - - This is the second item - - The last item is the best - - This paragraph includes a [link](#) - {% endcapture %} - {% include components/alert.html - content=markdown_content - %} -
    - -#### Kitchen sink - -#### Source - -```liquid -{% raw %}{% include components/alert.html - title="Pay attention" - content="This is the body of the alert" - level="danger" -%}{% endraw %} -``` - -#### Output - -
    - {% include components/alert.html - title="Pay attention" - content="This is the body of the alert" - level="danger" - %} -
    - -[bs-alert]: https://getbootstrap.com/docs/4.0/components/alerts/ diff --git a/src/collections/_dev_components/layout-components/platform-content/example_2/python.md b/src/collections/_dev_components/layout-components/platform-content/example_2/python.md deleted file mode 100644 index 2663b21471dd9..0000000000000 --- a/src/collections/_dev_components/layout-components/platform-content/example_2/python.md +++ /dev/null @@ -1,7 +0,0 @@ -### I am a Python example. - -You can do this to say hello: - -``` python -print("{{ page.example_string }}") -``` diff --git a/src/collections/_dev_components/layout-components/platform-content/example_2/ruby.md b/src/collections/_dev_components/layout-components/platform-content/example_2/ruby.md deleted file mode 100644 index 203a0f9b6c310..0000000000000 --- a/src/collections/_dev_components/layout-components/platform-content/example_2/ruby.md +++ /dev/null @@ -1,7 +0,0 @@ -### I am a Ruby example. - -You can do this to say hello: - -``` ruby -puts "{{ page.example_string }}" -``` diff --git a/src/collections/_dev_components/layout-components/platform-content/index.md b/src/collections/_dev_components/layout-components/platform-content/index.md deleted file mode 100644 index b0d5d8824f11a..0000000000000 --- a/src/collections/_dev_components/layout-components/platform-content/index.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Platform Content -source: components/platform_content.html -example_string: Hello world - -example_1: - JavaScript: | - ``` javascript - console.log("{{ page.example_string }}") - ``` - Python: | - ``` python - print("{{ page.example_string }}") - ``` - Ruby: | - ``` ruby - puts "{{ page.example_string }}" - ``` - -example_2: - JavaScript: | - ## I am an example about JavaScript - - Did you know 0 == false but 0 !== false? - Python: | - ``` - # This is a Python example. A python is a snake. - ``` - Ruby: | - - In Ruby - - You have to - - Say `end` a lot. - -example_3: - Python: Python Example - Ruby: Ruby Example ---- - -You can customize content by platform. Within a folder in the same directory as your document, add a file for each platform you would like to include, ensuring that name of the file matches a slug in *src/data/platforms.yml*, then use the include to specify which folder to include examples from. - -Content is run through the Liquid compiler, then through the Markdown compiler, making it possible to create dynamic, rich styled content. - -The switcher will globally remember the prefered language and load it by default until changed. If no prefered language is set, the first langage provided is the default. A content platform content block does not contain the preferred language, it will display the default language for the block. - -You may force the platform that is displayed on the page by appending a `platform=javascript` query parameter to the page url. This will cause subsequent pages in the browsing session to display that platform. Removing the query parameter will set the page back to the default behavior of looking for the prefered platform - -- `content=[]` _(required)_ A unique key to identify the switcher - -
    - -### Basic use - -#### File structure - -``` -_documentation/my-category/ - my-document.md - my-example/ - javascript.md - python.md - ruby.md -``` - -#### Source - -```liquid -{% raw %}{% include components/platform_content.html content_dir="my-example" %}{% endraw %} -``` - -#### Output - -
    -{% include components/platform_content.html content_dir="example_1" %} -
    - -### Mismatched platforms - -This example does not have a Javascript, while the others on the page do. Try -using the other switchers to see how this one handles falling back when -JavaScript is selected. - -#### File structure - -``` -_documentation/my-category/ - my-document.md - my-example/ - python.md - ruby.md -``` - -#### Source - -```liquid -{% raw %}--- -example_content: - Python: Python Example - Ruby: Ruby Example ---- - -{% include components/platform_content.html content_dir="my-example" %}{% endraw %} -``` - -#### Output - -
    -{% include components/platform_content.html content_dir="example_2" %} -
    diff --git a/src/collections/_dev_components/layout-components/user-content.md b/src/collections/_dev_components/layout-components/user-content.md deleted file mode 100644 index fb25d9f41710d..0000000000000 --- a/src/collections/_dev_components/layout-components/user-content.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: User Content -example_string: Hello world -example_1: - JavaScript: | - This is a JavaScript example. - - ``` javascript - console.log("Your DSN is ___PUBLIC_DSN___") - ``` - Python: | - This is a Python example. - - ``` python - print("Your DSN is ___PUBLIC_DSN___") - ``` - Ruby: | - This is a Ruby example. - - ``` ruby - puts "Your DSN is ___PUBLIC_DSN___" - ``` ---- - -It is possible to display a user's actual configuration information within code samples. This is done using one of the following keys: - -
    - -This feature only works within block level code examples, which are created using tripple tick ``` fenced code blocks in Markdown or using Jekyll's `highlight` tag. - -### Basic use - -#### Source - -```liquid -{% raw %}`⁣``javascript -console.log("Your DSN is _⁣__DSN___") -`⁣``{% endraw %} -``` - -{% include components/alert.html content="Do not copy and paste from this example. It contains invisible characters that prevent the tokens from rendering." %} - -#### Output - -
    -{% highlight javascript %} -console.log("Your DSN is ___DSN___") -{% endhighlight %} -
    diff --git a/src/collections/_dev_components/tags/version-added.md b/src/collections/_dev_components/tags/version-added.md new file mode 100644 index 0000000000000..29b592d995592 --- /dev/null +++ b/src/collections/_dev_components/tags/version-added.md @@ -0,0 +1,13 @@ +--- +title: Version Added +arguments: + - name: first + type: String + required: true + desc: Text that will be prepended with "New in" and wrapped in parenthesis +examples: + - title: Basic use + source: "{% version_added 8.4 %}" +--- + +Insert a note about when a feature was added.