Giter Site home page Giter Site logo

googlecodelabs / tools Goto Github PK

View Code? Open in Web Editor NEW
4.1K 246.0 1.1K 74.9 MB

Codelabs management & hosting tools

License: Apache License 2.0

Makefile 0.19% Go 37.68% HTML 28.88% JavaScript 21.81% Shell 0.43% Starlark 2.61% SCSS 7.25% Closure Templates 1.14%

tools's Issues

No keyboard navigation?

The only way I could scroll down the page in the ES6 and First Progressive Web App labs was by dragging the scrollbar down.

What happened: Page Down and down arrow both moved me to the next screen.
What should have happened: Down arrow should move me further down the screen, not to the next screen.

export/md: missing metadata

If you do the following:

$ claat export -f md $GDOC_ID

You get an MD file with no metadata section, the first line is a # tag. So when you go to export the md file to get servable HTML you get:

$ claat export index.md 
err	index.md invalid metadata format, missing at least id: map[]

SEO friendly?

At @RestyaPlatform we're very much interested to try codelabs (thanks for open sourcing it!) for documentation section of our Restyaboard (open source Trello alternative). We understand that it is static HTML. But, as it also uses Polymer, will there be any impact on SEO? TIA

export/md: durations are turned into sentences

I exported a Google Doc codelab to markdown:

$ claat export -f md 1YZj0tKwwRz1I8uJpW2J1FApD_a02Tmw8gWZvq-thfes

The markdown is mostly well-formed, but durations become italicized sentences:

## Set up the sample project

*Duration is 5 min*

claat should store oauth tokens

Running claat requires it to auth every, single, time, it's run. It would be awesome if it could store my oauth tokens, so I don't need to auth every time I run it.

We use it to deploy code labs to d.g.c/web, which means it's usually run 4 or 5 times a week by the same person.

Sanitize/clean metadata

Mostly for me so that I won't forget:

Sometimes metadata like URL may take a non-clean value such as code-\n\n\n-lab. Needs a clean up function.

Source format instructions not found

The help says that the source formats currently supported are:

  • Google Doc (Codelab Format, go/codelab-guide)
  • Markdown

However, i was unable to find any instructions on how to format the input document.

Generate FAQ in MarkDown

Accordingly to the Codelab Formatting Guide (external) in order to render FAQs we must follow this:

FAQs are easy to add. All the author needs to do is provide an unordered list of hyperlinks and preface it with a Heading 3 header with the exact text: Frequently Asked Questions. For example:

image

Output should look like this:
image

Doing so in MD we get the following
image

image

md: Support includecode tags

I'd love to see an ability to include code snippets in markdown codelabs like we already do in our "core" documentation.

This could be done in a few ways:

  • If devsite becomes the serving platform for codelabs then it might "just work" if the directive is left in the final HTML.
  • claat export could resolve these imports into static <pre> tags. Re-implementing the includecode feature is not hard (I've done it a few times).

For some reference, the syntax used on devsite is:

{% includecode github_path="user-repo/path/to/File.ext" region_tag="my_region" %}

Markdown does not respect line returns

If you have a line return in your Markdown, claat does not respect it. An example:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce condimentum pellentesque nisl vel pellentesque. Curabitur at ligula vitae tellus laoreet vehicula. Morbi egestas tincidunt commodo. Ut convallis porta risus. Sed interdum quam rutrum, molestie neque vitae, dignissim est. Donec eget rutrum sem. Donec nec lectus sed nisl vehicula pellentesque a ut nisi. Mauris pharetra pharetra arcu eu lacinia. Maecenas quis est quis sapien convallis ornare. Nulla vel pulvinar turpis, nec finibus elit. Cras pretium maximus cursus. Morbi vitae dolor mi. Morbi vel sodales lacus.

Praesent nec dolor in quam iaculis imperdiet. Praesent venenatis at purus non dignissim. In convallis et erat a ultrices. Nam dignissim justo at diam lobortis pellentesque consequat eget augue. Aliquam pellentesque tristique nisl sit amet pellentesque. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Mauris varius auctor gravida. Donec tempor feugiat metus in suscipit.

Will render as:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce condimentum pellentesque nisl vel pellentesque. Curabitur at ligula vitae tellus laoreet vehicula. Morbi egestas tincidunt commodo. Ut convallis porta risus. Sed interdum quam rutrum, molestie neque vitae, dignissim est. Donec eget rutrum sem. Donec nec lectus sed nisl vehicula pellentesque a ut nisi. Mauris pharetra pharetra arcu eu lacinia. Maecenas quis est quis sapien convallis ornare. Nulla vel pulvinar turpis, nec finibus elit. Cras pretium maximus cursus. Morbi vitae dolor mi. Morbi vel sodales lacus. Praesent nec dolor in quam iaculis imperdiet. Praesent venenatis at purus non dignissim. In convallis et erat a ultrices. Nam dignissim justo at diam lobortis pellentesque consequat eget augue. Aliquam pellentesque tristique nisl sit amet pellentesque. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Mauris varius auctor gravida. Donec tempor feugiat metus in suscipit.

Convert Formatting Guide doc to a wiki page

This is in reference to the Codelab Formatting Guide.

Similar to the Examples section of the Github Markdown guide, having examples people can just copy paste and then modify with their content I feel would be much more productive than instructing them on how to do formatting.

That way folks can just scan through the document and when they see something that looks like what they want to use, they just copy the content from the formatting guide Google Doc into their Lab Doc and modify/tweak.

My apologies if this has already been discussed and I messed it when searching.

Images displayed 100% full width

I am using Markdown to author the codelabs. My images are always displayed in full width. I have tried to use the html directly in Markdown but my style is tripped away on the rendered HTML.

This is how am showing the image ![App Overview](img/chuckes-app-overview.png)

I have also tried <img src="img/chuckes-app-overview.png" width="200" /> and <img src="img/chuckes-app-overview.png" style="max-width: 50%;"/> but none of this works.

image 1

ability to show/hide solutions

When creating labs, many times I find it desirable to provide a solution to the student if they can't figure out what to do. This request to make a formatting convention that when used turns the block of text, images, etc. into a show/hide button that defaults to hiding all the content and displaying the text show solution or similar. This way it's not immediately viewable on the screen but the student can click the button to show the solution.

The content that would be hidden and then shown when clicking the button may be a combination of any of the other already defined CodeLab formatting, with the exception this show/hide feature (no nested show/hide solutions).

CC @meiheptio

claat: cmd line argument for access token

In addition to storing credentials in $HOME/.config/claat, the program should also accept alternative credentials provided from the command line arguments.

For instance:

claat export -auth <access_token> ...other args...

This will allow to use claat binary in CI and other such systems where robots rule the world.

The -auth argument must take precedence over other credentials (if any).

How to create a codelab?

Sorry, I don't know my question is eligible or not. But currently I want to create a codelab-style tutorial on my own. Is there a guide to do it? Thank you.

claat drops text from hyperlink when exporting to markdown

When exporting to markdown, claat seems to drop the link text for some types of links. It appears to work fine when exporting as HTML.

From what I can tell, it happens when the hyperlink in the doc is meant to be a button (has a green background in docs).

Repro Steps:

  1. Export Your First PWA Code Lab (1rpHleSSeY-MJZ8JvncvYA8CFqlnlcrW8-a4uEaqizPY) as markdown.

Expected result:
No links in the form of [](https://github.com/googlecodelabs/your-first-pwapp/archive/master.zip)

md: Make exported markdown (from GDoc) match what you would hand-write

I want claat export -f md $GDOC_ID to match the style of a markdown file written manually by an author.

Here are some discrepancies I found in a codelab I happen to have hand-written as both a md file and a GDoc

Metadata

The exported metadata has some spurious line breaks and possibly uses some incorrect attribute IDs (or maybe my handwritten one had the wrong IDs).

Handwritten

---
id: firestore-android
summary: In this codelab you'll learn how to build an Android app that uses Cloud Firestore
author: [email protected]
categories: Firebase
tags: web, kiosk, firebase17, devfest-lon, io2018, tag-firebase, tag-cloud
status: Published
feedback_url: https://github.com/firebase/friendlyeats-android/issues

---

Exported

---
id: firestore-android
status: [published]
summary: In this codelab you'll learn how to build an Android app that uses Cloud Firestore.

categories: Firebase
tags: devfest-lon,firebase17,io2018,kiosk,tag-cloud,tag-firebase,web
feedback link: https://github.com/firebase/friendlyeats-android/issues


---

Durations

The exported codelab does not add the optional :ss to minute-durations, which makes reading less clear.

Handwritten

Duration: 1:00

Exported

Duration: 1

Code Blocks

The exported codelab uses the four-spaces-indent method for fenced code blocks. Using "```" makes the formatting more explicit. It also opens up future use of the Github-style "```language" format for specifying the language for pretty-printing.

Handwritten

\```
$ git clone https://github.com/firebase/friendlyeats-android
\```

Exported

    $ git clone https://github.com/firebase/friendlyeats-android

Bolding

This one is highly subjective but I find ** to be the more common way to add emphasis than __

Handwritten

click **Publish**

Exported

click __Publish__

Callouts

Callouts are broken when exporting from md to html. The new parser uses the special markdown infoboxes spec addition rather than the <aside> tag.

Exported

<aside class="special">

__Note__: this codelab demonstrates the real-time capabilities of Firestore, but it's also simple to fetch data without a listener.  You can call `get()` on any query or reference to fetch a data snapshot.
</aside>

Handwritten

positive
: **Note**: this codelab demonstrates the real-time capabilities of Firestore, but it's also simple to fetch data without a listener. You can call get() on any query or reference to fetch a data snapshot.

Adding more styled buttons

Hi all,

I would love to add more styled buttons to accompany our current green download button.

Also, is it more constructive for me to introduce feature request and gauge community interest here or in this Google Group?

Best,
Henry

Change the default colors

Am not sure if this is already supported, i would like to change the default colors used on the rendered html output. I have used Chrome developer tools to change the colors but i would prefer to pass some params and get the color changed. It would nice if i can do this when i export.

image

claat tool should auto-generate author tag for web fundamentals

Consider supporting an optional metadata field for including authorship attribution in the generated codelab.

@petele - Did you want this to generate a WF specific tag in the generated markdown? Or include an author field in the codelab.json file, which could be parsed by the web fundamentals build tooling?

md: Images stretched to 100% width

When I make a codelab from a Google doc it appears that images are given a max width attribute. With markdown they are not, which means that the width: 100% style from step-style.html takes over.

I get this:
image

But I want this:
image

Create a claat build command

Hi,

First I want to thank you for your tool. I am started using it for my own codelabs.

If I understand well, the basic workflow is :

claat export ...
claat serve

The last command is important because all bower dependencies will be downloaded.

Do we have another command for downloading these dependencies, without launching an HTTP server. For example a claat build ?

Second question, I am looking for a docker image in order to launch claat commands without Go on my system. Do you have this image ?

Thanks again.

claat: support user-input in command-line snippets

The command-line snippet can be enhanced in order to show which is the user-input text among the text output of the commands.

Existing codelabs are using different conventions in showing command-line commands. Some are omitting the shell prompt altogether, others do not show any output from the commands which can be confusing to the users.

For a codelabs author, they should just make bold the parts of the command-line input that is actual user-input. Then claat should show this text in a distinctive way to denote user-input.

See screenshot of commands with user-input in bold

formatting oddness with multiple bolds in one line

I have a Google Doc with a bulleted list and each bullet has bolder, then monospaced font, then plain text, then bolding and then plain text. However the formatting comes out odd in regards to the formatting on Qwiklab. The Google Doc and the Chrome Plugin appear to render properly though.

See the following screenshots to help.

Google Doc
screen shot 2017-08-07 at 2 52 39 pm

Chrome Plugin
screen shot 2017-08-07 at 2 53 15 pm

Qwiklabs
screen shot 2017-08-07 at 2 53 41 pm

Markdown formatting not working

Apologies if this is documented somewhere already. Am using the standard markdown, but when i export and the serve the file, the markdown for bold or code doesnt show up.

Which markdown tags are supported? Is bold not supported? Or italics. Part of my code does get formatted but not all of it.

I also can not get a new line. How do i add a new line?

Here is the contents of my test file below :

author: Mariusz Saramak
summary: TomTom Creating a custom Gangnam vector map style
categories: sdk
environments: sql
status: draft
feedback link: github.com/tomtom-gangdam-style-for-map
analytics account: 0

# Demo Codelab

## Introduction

* Modify a default TomTom style for vector maps with use of the Maputnik editor `code`
* Apply the newly created style
Prerequesites
* API key
* Npm and Node.js

Negative
: To get an API key you need register or sign in to TomTom Developer Portal. Request an evaluation API key to access the service you want to use the SDK with.


Positive
: It is possible to have a single key(app) for all TomTom services, but you can also choose : to have individual keys for the different services.

## Set STATISTICS IO 
Duration 00:05

`SET STATISTICS IO` displays the amount of disk activity generated by a query. To enable it, run the following statement:

```sql
SET STATISTICS TIME ON
```

and now can run a query and check the message tab :

```sql
SELECT DISTINCT(CustomerID)
FROM Sales.
```

## Clean the Buffer Cache
Duration 00:05

We can remove all the cached pages from the buffer by running :

```sql
DBCC DROPCLEANBUFFERS
```

When testing, its recommended to clean the buffer and run the query. This will give you a true picture of the performance of the query.

Then run the following query:

```sql
SELECT * FROM Sales.SalesOrderDetail WHERE ProductID = 870
```
It will show an output similar to the following:

Here are the definitions of these items, which all use 8K pages:

1. Logical reads Number of pages read from the buffer pool.

2. **Physical reads** Number of pages read from disk.

3. **Read-ahead reads** Read-ahead is a performance optimization mechanism that anticipates the needed data pages and reads them from disk. It can read up to 64 contiguous pages from one data file.

- **Lob logical** reads Number of large object (LOB) pages read from the buffer pool.

- **Lob physical** reads Number of large object (LOB) pages read from disk.

- **Lob read-ahead** reads Number of large object (LOB) pages read from disk using the read-ahead mechanism, as explained earlier.

Now, if you run the same query again, you will no longer get physical and read-ahead reads. 


**Scan count**is defined as the number of seeks or scans started after reaching the leaf level (that is, the bottom level of an index). The only case when scan count will return 0 is when you’re seeking for only one value on a unique index, like in the following example:

```sql
SELECT * FROM Sales.SalesOrderHeader WHERE SalesOrderID = 51119
```

If you try the following query, in which SalesOrderID is defined in a nonunique index and can return more than one record, you can see that scan count now returns 1:

```sql
SELECT * FROM Sales.SalesOrderDetail WHERE SalesOrderID = 51119
```

Finally, in the following example, scan count is 4 because SQL Server has to perform four seeks:

```sql
SELECT * FROM Sales.SalesOrderHeader WHERE SalesOrderID IN (51119, 43664, 63371, 75119)
```

## Removing Plans from the Plan Cache
Duration 00:05

![Image](images/lob.jpg)

You can use a few different commands to remove plans from the plan cache :


`DBCC FREEPROCCACHE` statement can be used to remove all the entries from the plan cache. It can also accept a plan handle or a SQL handle to remove only specific plans.

* _DBCC FREEPROCCACHE_ statement can be used to remove all the entries from the plan cache. It can also accept a plan handle or a SQL handle to remove only specific plans.
* __DBCC FREESYSTEMCACHE__ statement can be used to remove all the elements from the plan cache or only the elements associated with a Resource Governor pool name.
* **DBCC FLUSHPROCINDB** can be used to remove all the cached plans for a particular database
* `DBCC DROPCLEANBUFFERS` statement can be used to remove all the buffers from the buffer pool. You can use this statement in cases where you want to simulate a query starting with a cold cache

```java
/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.android.codelabs.paging.db

import android.arch.lifecycle.LiveData
import android.arch.persistence.room.Dao
import android.arch.persistence.room.Insert
import android.arch.persistence.room.OnConflictStrategy
import android.arch.persistence.room.Query
import com.example.android.codelabs.paging.model.Repo
import javax.sql.DataSource

/**
 * Room data access object for accessing the [Repo] table.
 */
@Dao
interface RepoDao {

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    fun insert(posts: List)

    // Do a similar query as the search API:
    // Look for repos that contain the query string in the name or in the description
    // and order those results descending, by the number of stars and then by name
    @Query("SELECT * FROM repos WHERE (name LIKE :queryString) OR (description LIKE " +
            ":queryString) ORDER BY stars DESC, name ASC")
    fun reposByName(queryString: String): LiveData>

//    @Query("SELECT * FROM repos WHERE (name LIKE :queryString) OR (description LIKE " +
//            ":queryString) ORDER BY stars DESC, name ASC")
//    fun  reposByTA(queryString: String) : DataSource.Factory

}
```

demo_codelab

export: allow fetching of remote markdown

Would want this:

$ claat export https://github.com/firebase/friendlyeats-android/blob/master/docs/codelab.md

To produce this meatdata:

{
  "environment": "web",
  "source": "https://github.com/firebase/friendlyeats-android/blob/master/docs/codelab.md",
  "format": "html",
  "prefix": "../../",
  "mainga": "UA-49880327-14",
  "updated": "2018-06-20T15:15:24-07:00",
  "id": "firestore-android",
  "duration": 37,
  "title": "Cloud Firestore Android Codelab",
  "author": "[email protected]",
  "summary": "In this codelab you’ll learn how to build an Android app that uses Cloud Firestore",
  "theme": "",
  "status": [
    "published"
  ],
  "category": [
    "firebase"
  ],
  "tags": [
    "devfest-lon",
    "firebase17",
    "io2018",
    "kiosk",
    "tag-cloud",
    "tag-firebase",
    "web"
  ],
  "url": "firestore-android"
}

md: Single line breaks should be ignored

Consider the following ways to write the same text:

(1) One line:

In this codelab you will build a restaurant recommendation app on Android backed by Cloud Firestore. You will learn how to:

(2) Single line break:

In this codelab you will build a restaurant recommendation app on Android backed by Cloud Firestore. 
You will learn how to:

(3) Double line break:

In this codelab you will build a restaurant recommendation app on Android backed by Cloud Firestore. 

You will learn how to:

Right now only (1) renders as a single <p> tag, the other two insert <br> wherever a newline is found. I think that (2) should render as a single <p> tag to enable enforcing line-length limits in md source without affecting the presentation.

claat flags = options?

From trying the claat tool, it seems like flags are options. So when help defines claat <cmd> [options] src [src ...] I was not sure if the flags were the options.

Maybe update the --help
from:
claat <cmd> [options] src [src ...]
to:
claat <cmd> [flags] src [src ...]

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.