mermade / reslate Goto Github PK

View Code? Open in Web Editor NEW

139.0 5.0 42.0 573 KB

Beautiful static documentation for your API

Home Page: https://mermade.github.io/reslate/

License: Apache License 2.0

JavaScript 16.76% Dockerfile 0.19% HTML 21.04% SCSS 27.71% CSS 28.87% EJS 5.42%

api documentation documentation-generator static-site-generator api-documentation

reslate's Introduction

Slate v3 POC

Proof-of-concept Slate v3 using eleventy as the static site generator.

Features

Out-of-the-box syntax highlighting for over 200 languages, no configuration required.

Install

Requires an LTS version of Node.js

Clone the repository
npm i

Create your Node.js project (npm init)
Add reslate as a (dev)dependency (npm i [--save-dev] reslate)
npx reslate init

Running

To build: npm run build
To debug: npm run debug
To serve: npm run serve and browse to http://localhost:4567

(If installed as a dependency, use npx reslate [build|debug|serve])

TODO

Watch scss files
Option to use lunr server-side / across multiple files #1006
GitHub emoji shortcuts (as in Shins), yea or nay?
Specify additional CSS includes in header?

Additional plugin possibilities

https://www.11ty.dev/docs/config/#transforms-example-minify-html-output

reslate's People

Contributors

Stargazers

Watchers

reslate's Issues

Build script throws error: code_clipboard is not defined

Bug Description
I'm using the NPM version of reslate (3.0.0-1) to convert some widdershins markdown of an OpenAPI 3.0.3 API definition. When I run npx reslate build, I get the following output:

Compiled ../../slate/css/print.scss to ../../slate/css/print.css.
Compiled ../../slate/css/screen.scss to ../../slate/css/screen.css.
Error writing templates: (more in DEBUG output)
> Having trouble writing template: ../../_site/index.html

`TemplateWriterWriteError` was thrown
> ../../_includes/slate.ejs:38
    36|     <script src="slate/js/app/search.js"></script>
    37|     <% } %>
 >> 38|     <% if (code_clipboard) { %>
    39|     <script src="slate/js/app/copy.js"></script>
    40|     <% } %>
    41|     <script type="text/javascript">

code_clipboard is not defined

`ReferenceError` was thrown:
    ReferenceError: ../../_includes/slate.ejs:38
        36|     <script src="slate/js/app/search.js"></script>
        37|     <% } %>
     >> 38|     <% if (code_clipboard) { %>
        39|     <script src="slate/js/app/copy.js"></script>
        40|     <% } %>
        41|     <script type="text/javascript">

    code_clipboard is not defined
        at eval (../../_includes/slate.ejs:25:8)
        at slate (/home/****/test-api/node_modules/ejs/lib/ejs.js:682:17)
        at /home/****/test-api/node_modules/@11ty/eleventy/src/Engines/Ejs.js:50:14
        at TemplateLayout.render (/home/****/test-api/node_modules/@11ty/eleventy/src/TemplateLayout.js:152:31)
Problem writing Eleventy templates: (more in DEBUG output)
> Having trouble writing template: ../../_site/index.html

`TemplateWriterWriteError` was thrown
> ../../_includes/slate.ejs:38
    36|     <script src="slate/js/app/search.js"></script>
    37|     <% } %>
 >> 38|     <% if (code_clipboard) { %>
    39|     <script src="slate/js/app/copy.js"></script>
    40|     <% } %>
    41|     <script type="text/javascript">

code_clipboard is not defined

`ReferenceError` was thrown:
    ReferenceError: ../../_includes/slate.ejs:38
        36|     <script src="slate/js/app/search.js"></script>
        37|     <% } %>
     >> 38|     <% if (code_clipboard) { %>
        39|     <script src="slate/js/app/copy.js"></script>
        40|     <% } %>
        41|     <script type="text/javascript">

    code_clipboard is not defined
        at eval (../../_includes/slate.ejs:25:8)
        at slate (/home/****/node_modules/ejs/lib/ejs.js:682:17)
        at /home/****/test-api/node_modules/@11ty/eleventy/src/Engines/Ejs.js:50:14
        at TemplateLayout.render (/home/****/test-api/node_modules/@11ty/eleventy/src/TemplateLayout.js:152:31)
Benchmark (Data): `../../index.11tydata.js` took 49ms (8.1%)
Copied 9 files / Wrote 0 files in 0.17 seconds (v0.11.1)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build.local: `npm run build.sass.local && cross-var npx eleventy --input=$SLATEDIR/*.md --output=$SLATEDIR/_site`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] build.local script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.
npm WARN Local package.json exists, but node_modules missing, did you mean to install?

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/****/.npm/_logs/2020-12-16T06_02_05_843Z-debug.log

The OpenAPI YAML code is as follows:

openapi: 3.0.3
info:
  title: "Test API"
  version: 0.0.1

servers:
  - url: https://api.example.com
    description: Staging Server

paths:
  /test:
    get:
      summary: Get credentials for API access
      description: Returns OAuth2 tokens upon successful validation of a given API key
      operationId: test
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - apiKey
              properties:
                apiKey:
                  type: string
      responses:
        "200":
          description: Returns OAuth2 tokens
          content:
            application/json:
              schema:
                type: object
                required:
                  - accessToken
                  - expiresIn
                properties:
                  accessToken:
                    type: string
                  expiresIn:
                    type: integer
                example:
                  accessToken: "aaaaa.bbbbb.ccccc"
                  expiresIn: 36000

I am running Ubuntu 18.04.5 via WSL2.

Reslate not found on npm registry

Bug Description
npm i reslate and npx reslate init both does not work. misleading install instructions on readme.md?

Screenshots

$ npm i reslate
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/reslate - Not found
npm ERR! 404 
npm ERR! 404  'reslate@latest' is not in the npm registry.
npm ERR! 404 You should bug the author to publish it (or use the name yourself!)
npm ERR! 404 
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

npm ERR! A complete log of this run can be found in:

$ npx reslate init
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/reslate - Not found
npm ERR! 404 
npm ERR! 404  'reslate@latest' is not in the npm registry.
npm ERR! 404 You should bug the author to publish it (or use the name yourself!)
npm ERR! 404 
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

npm ERR! A complete log of this run can be found in:

also https://www.npmjs.com/search?q=reslate
yields 0 packages found

Browser (please complete the following information):

OS: Any
Browser Node
Version 10.22.1

Last upstream Slate commit (run git log --author="Robert Lord" | head -n 1):
a8a65b0

Consider removing 'cross-var' as a dependency

Bug Description
'cross-var' has been unmaintained for more than 3 years now, I just came across a weird bug that prevents npx reslate ... from running correctly when there is a parent directory named src in the whole hierarchy.

I'm posting the error description just in case some one came across it:

ReferenceError: Unknown plugin "transform-runtime" specified in.....

You can check the issue at cross-var here: elijahmanor/cross-var#17

Cannot run reslate as a dependency.

Bug Description
Following the instructions at https://github.com/Mermade/reslate to set it up I:

Created my node project using npm init
Run npm i --save-dev reslate
Run npx reslate init
Run npx reslate serve

The serve fails with the following message "no such file or directory, stat ...$SLATEDIR` (clearer in the image).

I'm not sure if this helps, but If I navigate to node_modules\reslate\package.json and replace all of the $SLATEDIR variables with ../.., it successfully serves. It seems like it's passing the slatedir variable through for the first part of the call (build), but not for the serve itself.

Screenshots
If applicable, add screenshots to help explain your problem.

Browser (please complete the following information):

OS: Windows 10
Node: v14.15.1

Last upstream Slate commit (run git log --author="Robert Lord" | head -n 1):
Put the commit hash here

'env: node\r: No such file or directory' - related to yarn, with reslate v3.0.0-5

Bug Description
This command:

npx reslate build

gives this error:

 env: node\r: No such file or directory

Reverting to version 3.0.0-4 solves this problem.

Steps to reproduce:

install reslate (yarn add reslate)
npx reslate init
npx reslate build

Screenshots

Browser:

OS: MacOS BigSur
Version: 11.4

Lack of copy.js breaks language selection

Bug Description
I think the fix in 3.0.0-2 (ea8371c) has revealed/triggered a bug whereby the language selection tabs don't trigger the example code to switch.

I don't have code_clipboard defined in my starting Markdown; that's just what was generated by widdershins, which doesn't seem to define code_clipboard (the word "code_clipboard" doesn't appear anywhere in their repo)

This results in slate/js/app/copy.js not being included in the index.html. That then results in the following error to the console:

jQuery.Deferred exception: setupCodeCopy is not defined setupLanguages@file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/app/lang.js line 37 > srcScript:150:9
@file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/index.html?javascript#getitems line 37 > inlineScript:29:23
e@file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/lib/jquery.min.js line 37 > srcScript:2:30005
l/</t<@file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/lib/jquery.min.js line 37 > srcScript:2:30307
activateLanguage@file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/app/lang.js:37:5
@file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/app/lang.js:176:23
dispatch@file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/lib/jquery.min.js:2:43090
add/v.handle@file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/lib/jquery.min.js:2:41074
---
Uncaught ReferenceError: setupCodeCopy is not defined
    setupLanguages file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/app/lang.js line 37 > srcScript:150
    <anonymous> file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/index.html?javascript#getmachines line 37 > inlineScript:29
    jQuery 2
    activateLanguage file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/app/lang.js:37
    <anonymous> file:///C:/Users/andy/workspace/gitea/Proj/proj-api-docs/_site/slate/js/app/lang.js:176
    jQuery 2

So setupLanguages requires code from copy.js, that isn't there if you don't explicitly define and set code_clipboard to true.

Note that I'm also hitting #25, so I've had to implemented workarounds to get past that - basically copying in the missing .js files.

Screenshots

"Shell" highlighted, only that isn't the shell code:

"Python" highlighted, but it's the same sample code:

Browser (please complete the following information):

OS: Windows 10
Browser: Firefix / Chrome
Version: 84.0.1 /

Last upstream Slate commit (run git log --author="Robert Lord" | head -n 1):
This is using 3.0.0-2

Slate-bundled JS files generated as broken symlinks

Bug Description
As of 3.0.0-2, I am able to build and serve the documentation site successfully. However, there appears to be an error with several of the JS files from Slate that get generated, namely "imagesloaded.min.js", "jquery.min.js", and "lunr.min.js". The error seems to stem from the call to npx reslate init, where the code files that get generated are symlinks instead of the files themselves, and inspecting these symlinks reveals them to be broken. If I look in the "node_modules" directory for reslate, the source files for these files are broken symlinks as well.

The symlinks are copied to the output upon running npx reslate build, which results in several aspects of the final site not working properly. For example, the code snippet column shows the sample code from all languages at once, and clicking the language tabs does nothing.

Here is the directory of my API description after having only run npx reslate init (note the curled arrows by the aforementioned files indicating they are symlinks and inspecting the files results in a read error):

And here is the resulting web page (note the code samples for Ruby, Python, Shell, and JavaScript are all being displayed simultaneously):

And this is the console output from the web page (the errors regarding $ would be because the jQuery script isn't being loaded):

jquery.min.js:1 Failed to load resource: the server responded with a status of 404 (Not Found)
imagesloaded.min.js:1 Failed to load resource: the server responded with a status of 404 (Not Found)
lunr.min.js:1 Failed to load resource: the server responded with a status of 404 (Not Found)
jquery.highlight.js:46 Uncaught ReferenceError: jQuery is not defined
    at jquery.highlight.js:46
imagesloaded.min.js:1 Failed to load resource: the server responded with a status of 404 (Not Found)
lunr.min.js:1 Failed to load resource: the server responded with a status of 404 (Not Found)
lang.js:172 Uncaught ReferenceError: $ is not defined
    at lang.js:172
    at lang.js:180
search.js:36 Uncaught ReferenceError: $ is not defined
    at search.js:36
    at search.js:101
(index):32 Uncaught ReferenceError: $ is not defined
    at (index):32

mermade / reslate Goto Github PK

reslate's Introduction

Slate v3 POC

Features

Install

Running

TODO

Additional plugin possibilities

reslate's People

Contributors

Stargazers

Watchers

Forkers

reslate's Issues

Recommend Projects

Recommend Topics

Recommend Org